1 #define PETSCMAT_DLL 2 3 /* 4 This is where the abstract matrix operations are defined 5 */ 6 7 #include "src/mat/matimpl.h" /*I "petscmat.h" I*/ 8 #include "vecimpl.h" 9 10 /* Logging support */ 11 PetscCookie PETSCMAT_DLLEXPORT MAT_COOKIE = 0; 12 PetscEvent MAT_Mult = 0, MAT_Mults = 0, MAT_MultConstrained = 0, MAT_MultAdd = 0, MAT_MultTranspose = 0; 13 PetscEvent MAT_MultTransposeConstrained = 0, MAT_MultTransposeAdd = 0, MAT_Solve = 0, MAT_Solves = 0, MAT_SolveAdd = 0, MAT_SolveTranspose = 0; 14 PetscEvent MAT_SolveTransposeAdd = 0, MAT_Relax = 0, MAT_ForwardSolve = 0, MAT_BackwardSolve = 0, MAT_LUFactor = 0, MAT_LUFactorSymbolic = 0; 15 PetscEvent MAT_LUFactorNumeric = 0, MAT_CholeskyFactor = 0, MAT_CholeskyFactorSymbolic = 0, MAT_CholeskyFactorNumeric = 0, MAT_ILUFactor = 0; 16 PetscEvent MAT_ILUFactorSymbolic = 0, MAT_ICCFactorSymbolic = 0, MAT_Copy = 0, MAT_Convert = 0, MAT_Scale = 0, MAT_AssemblyBegin = 0; 17 PetscEvent MAT_AssemblyEnd = 0, MAT_SetValues = 0, MAT_GetValues = 0, MAT_GetRow = 0, MAT_GetSubMatrices = 0, MAT_GetColoring = 0, MAT_GetOrdering = 0; 18 PetscEvent MAT_IncreaseOverlap = 0, MAT_Partitioning = 0, MAT_ZeroEntries = 0, MAT_Load = 0, MAT_View = 0, MAT_AXPY = 0, MAT_FDColoringCreate = 0; 19 PetscEvent MAT_FDColoringApply = 0,MAT_Transpose = 0,MAT_FDColoringFunction = 0; 20 PetscEvent MAT_MatMult = 0, MAT_MatMultSymbolic = 0, MAT_MatMultNumeric = 0; 21 PetscEvent MAT_PtAP = 0, MAT_PtAPSymbolic = 0, MAT_PtAPNumeric = 0; 22 PetscEvent MAT_MatMultTranspose = 0, MAT_MatMultTransposeSymbolic = 0, MAT_MatMultTransposeNumeric = 0; 23 24 /* nasty global values for MatSetValue() */ 25 PetscInt PETSCMAT_DLLEXPORT MatSetValue_Row = 0; 26 PetscInt PETSCMAT_DLLEXPORT MatSetValue_Column = 0; 27 PetscScalar PETSCMAT_DLLEXPORT MatSetValue_Value = 0.0; 28 29 #undef __FUNCT__ 30 #define __FUNCT__ "MatGetRow" 31 /*@C 32 MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow() 33 for each row that you get to ensure that your application does 34 not bleed memory. 35 36 Not Collective 37 38 Input Parameters: 39 + mat - the matrix 40 - row - the row to get 41 42 Output Parameters: 43 + ncols - if not NULL, the number of nonzeros in the row 44 . cols - if not NULL, the column numbers 45 - vals - if not NULL, the values 46 47 Notes: 48 This routine is provided for people who need to have direct access 49 to the structure of a matrix. We hope that we provide enough 50 high-level matrix routines that few users will need it. 51 52 MatGetRow() always returns 0-based column indices, regardless of 53 whether the internal representation is 0-based (default) or 1-based. 54 55 For better efficiency, set cols and/or vals to PETSC_NULL if you do 56 not wish to extract these quantities. 57 58 The user can only examine the values extracted with MatGetRow(); 59 the values cannot be altered. To change the matrix entries, one 60 must use MatSetValues(). 61 62 You can only have one call to MatGetRow() outstanding for a particular 63 matrix at a time, per processor. MatGetRow() can only obtain rows 64 associated with the given processor, it cannot get rows from the 65 other processors; for that we suggest using MatGetSubMatrices(), then 66 MatGetRow() on the submatrix. The row indix passed to MatGetRows() 67 is in the global number of rows. 68 69 Fortran Notes: 70 The calling sequence from Fortran is 71 .vb 72 MatGetRow(matrix,row,ncols,cols,values,ierr) 73 Mat matrix (input) 74 integer row (input) 75 integer ncols (output) 76 integer cols(maxcols) (output) 77 double precision (or double complex) values(maxcols) output 78 .ve 79 where maxcols >= maximum nonzeros in any row of the matrix. 80 81 82 Caution: 83 Do not try to change the contents of the output arrays (cols and vals). 84 In some cases, this may corrupt the matrix. 85 86 Level: advanced 87 88 Concepts: matrices^row access 89 90 .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal() 91 @*/ 92 93 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[]) 94 { 95 PetscErrorCode ierr; 96 PetscInt incols; 97 98 PetscFunctionBegin; 99 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 100 PetscValidType(mat,1); 101 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 102 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 103 if (!mat->ops->getrow) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 104 ierr = MatPreallocated(mat);CHKERRQ(ierr); 105 ierr = PetscLogEventBegin(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 106 ierr = (*mat->ops->getrow)(mat,row,&incols,(PetscInt **)cols,(PetscScalar **)vals);CHKERRQ(ierr); 107 if (ncols) *ncols = incols; 108 ierr = PetscLogEventEnd(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 109 PetscFunctionReturn(0); 110 } 111 112 #undef __FUNCT__ 113 #define __FUNCT__ "MatConjugate" 114 /*@C 115 MatConjugate - replaces the matrix values with their complex conjugates 116 117 Collective on Mat 118 119 Input Parameters: 120 . mat - the matrix 121 122 Level: advanced 123 124 .seealso: VecConjugate() 125 @*/ 126 PetscErrorCode PETSCMAT_DLLEXPORT MatConjugate(Mat mat) 127 { 128 PetscErrorCode ierr; 129 130 PetscFunctionBegin; 131 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 132 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 133 if (!mat->ops->conjugate) SETERRQ(PETSC_ERR_SUP,"Not provided for this matrix format, send email to petsc-maint@mcs.anl.gov"); 134 ierr = (*mat->ops->conjugate)(mat);CHKERRQ(ierr); 135 PetscFunctionReturn(0); 136 } 137 138 #undef __FUNCT__ 139 #define __FUNCT__ "MatRestoreRow" 140 /*@C 141 MatRestoreRow - Frees any temporary space allocated by MatGetRow(). 142 143 Not Collective 144 145 Input Parameters: 146 + mat - the matrix 147 . row - the row to get 148 . ncols, cols - the number of nonzeros and their columns 149 - vals - if nonzero the column values 150 151 Notes: 152 This routine should be called after you have finished examining the entries. 153 154 Fortran Notes: 155 The calling sequence from Fortran is 156 .vb 157 MatRestoreRow(matrix,row,ncols,cols,values,ierr) 158 Mat matrix (input) 159 integer row (input) 160 integer ncols (output) 161 integer cols(maxcols) (output) 162 double precision (or double complex) values(maxcols) output 163 .ve 164 Where maxcols >= maximum nonzeros in any row of the matrix. 165 166 In Fortran MatRestoreRow() MUST be called after MatGetRow() 167 before another call to MatGetRow() can be made. 168 169 Level: advanced 170 171 .seealso: MatGetRow() 172 @*/ 173 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRow(Mat mat,PetscInt row,PetscInt *ncols,const PetscInt *cols[],const PetscScalar *vals[]) 174 { 175 PetscErrorCode ierr; 176 177 PetscFunctionBegin; 178 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 179 PetscValidIntPointer(ncols,3); 180 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 181 if (!mat->ops->restorerow) PetscFunctionReturn(0); 182 ierr = (*mat->ops->restorerow)(mat,row,ncols,(PetscInt **)cols,(PetscScalar **)vals);CHKERRQ(ierr); 183 PetscFunctionReturn(0); 184 } 185 186 #undef __FUNCT__ 187 #define __FUNCT__ "MatView" 188 /*@C 189 MatView - Visualizes a matrix object. 190 191 Collective on Mat 192 193 Input Parameters: 194 + mat - the matrix 195 - viewer - visualization context 196 197 Notes: 198 The available visualization contexts include 199 + PETSC_VIEWER_STDOUT_SELF - standard output (default) 200 . PETSC_VIEWER_STDOUT_WORLD - synchronized standard 201 output where only the first processor opens 202 the file. All other processors send their 203 data to the first processor to print. 204 - PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure 205 206 The user can open alternative visualization contexts with 207 + PetscViewerASCIIOpen() - Outputs matrix to a specified file 208 . PetscViewerBinaryOpen() - Outputs matrix in binary to a 209 specified file; corresponding input uses MatLoad() 210 . PetscViewerDrawOpen() - Outputs nonzero matrix structure to 211 an X window display 212 - PetscViewerSocketOpen() - Outputs matrix to Socket viewer. 213 Currently only the sequential dense and AIJ 214 matrix types support the Socket viewer. 215 216 The user can call PetscViewerSetFormat() to specify the output 217 format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF, 218 PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include 219 + PETSC_VIEWER_ASCII_DEFAULT - default, prints matrix contents 220 . PETSC_VIEWER_ASCII_MATLAB - prints matrix contents in Matlab format 221 . PETSC_VIEWER_ASCII_DENSE - prints entire matrix including zeros 222 . PETSC_VIEWER_ASCII_COMMON - prints matrix contents, using a sparse 223 format common among all matrix types 224 . PETSC_VIEWER_ASCII_IMPL - prints matrix contents, using an implementation-specific 225 format (which is in many cases the same as the default) 226 . PETSC_VIEWER_ASCII_INFO - prints basic information about the matrix 227 size and structure (not the matrix entries) 228 . PETSC_VIEWER_ASCII_INFO_DETAIL - prints more detailed information about 229 the matrix structure 230 231 Options Database Keys: 232 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 233 . -mat_view_info_detailed - Prints more detailed info 234 . -mat_view - Prints matrix in ASCII format 235 . -mat_view_matlab - Prints matrix in Matlab format 236 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 237 . -display <name> - Sets display name (default is host) 238 . -draw_pause <sec> - Sets number of seconds to pause after display 239 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 240 . -viewer_socket_machine <machine> 241 . -viewer_socket_port <port> 242 . -mat_view_binary - save matrix to file in binary format 243 - -viewer_binary_filename <name> 244 Level: beginner 245 246 Concepts: matrices^viewing 247 Concepts: matrices^plotting 248 Concepts: matrices^printing 249 250 .seealso: PetscViewerSetFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(), 251 PetscViewerSocketOpen(), PetscViewerBinaryOpen(), MatLoad() 252 @*/ 253 PetscErrorCode PETSCMAT_DLLEXPORT MatView(Mat mat,PetscViewer viewer) 254 { 255 PetscErrorCode ierr; 256 PetscInt rows,cols; 257 PetscTruth iascii; 258 char *cstr; 259 PetscViewerFormat format; 260 261 PetscFunctionBegin; 262 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 263 PetscValidType(mat,1); 264 if (!viewer) viewer = PETSC_VIEWER_STDOUT_(mat->comm); 265 PetscValidHeaderSpecific(viewer,PETSC_VIEWER_COOKIE,2); 266 PetscCheckSameComm(mat,1,viewer,2); 267 if (!mat->assembled) SETERRQ(PETSC_ERR_ORDER,"Must call MatAssemblyBegin/End() before viewing matrix"); 268 ierr = MatPreallocated(mat);CHKERRQ(ierr); 269 270 ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);CHKERRQ(ierr); 271 if (iascii) { 272 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 273 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 274 if (mat->prefix) { 275 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:(%s)\n",mat->prefix);CHKERRQ(ierr); 276 } else { 277 ierr = PetscViewerASCIIPrintf(viewer,"Matrix Object:\n");CHKERRQ(ierr); 278 } 279 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 280 ierr = MatGetType(mat,&cstr);CHKERRQ(ierr); 281 ierr = MatGetSize(mat,&rows,&cols);CHKERRQ(ierr); 282 ierr = PetscViewerASCIIPrintf(viewer,"type=%s, rows=%D, cols=%D\n",cstr,rows,cols);CHKERRQ(ierr); 283 if (mat->ops->getinfo) { 284 MatInfo info; 285 ierr = MatGetInfo(mat,MAT_GLOBAL_SUM,&info);CHKERRQ(ierr); 286 ierr = PetscViewerASCIIPrintf(viewer,"total: nonzeros=%D, allocated nonzeros=%D\n", 287 (PetscInt)info.nz_used,(PetscInt)info.nz_allocated);CHKERRQ(ierr); 288 } 289 } 290 } 291 if (mat->ops->view) { 292 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 293 ierr = (*mat->ops->view)(mat,viewer);CHKERRQ(ierr); 294 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 295 } else if (!iascii) { 296 SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported",((PetscObject)viewer)->type_name); 297 } 298 if (iascii) { 299 ierr = PetscViewerGetFormat(viewer,&format);CHKERRQ(ierr); 300 if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) { 301 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 302 } 303 } 304 PetscFunctionReturn(0); 305 } 306 307 #undef __FUNCT__ 308 #define __FUNCT__ "MatScaleSystem" 309 /*@C 310 MatScaleSystem - Scale a vector solution and right hand side to 311 match the scaling of a scaled matrix. 312 313 Collective on Mat 314 315 Input Parameter: 316 + mat - the matrix 317 . x - solution vector (or PETSC_NULL) 318 - b - right hand side vector (or PETSC_NULL) 319 320 321 Notes: 322 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 323 internally scaled, so this does nothing. For MPIROWBS it 324 permutes and diagonally scales. 325 326 The KSP methods automatically call this routine when required 327 (via PCPreSolve()) so it is rarely used directly. 328 329 Level: Developer 330 331 Concepts: matrices^scaling 332 333 .seealso: MatUseScaledForm(), MatUnScaleSystem() 334 @*/ 335 PetscErrorCode PETSCMAT_DLLEXPORT MatScaleSystem(Mat mat,Vec x,Vec b) 336 { 337 PetscErrorCode ierr; 338 339 PetscFunctionBegin; 340 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 341 PetscValidType(mat,1); 342 ierr = MatPreallocated(mat);CHKERRQ(ierr); 343 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 344 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 345 346 if (mat->ops->scalesystem) { 347 ierr = (*mat->ops->scalesystem)(mat,x,b);CHKERRQ(ierr); 348 } 349 PetscFunctionReturn(0); 350 } 351 352 #undef __FUNCT__ 353 #define __FUNCT__ "MatUnScaleSystem" 354 /*@C 355 MatUnScaleSystem - Unscales a vector solution and right hand side to 356 match the original scaling of a scaled matrix. 357 358 Collective on Mat 359 360 Input Parameter: 361 + mat - the matrix 362 . x - solution vector (or PETSC_NULL) 363 - b - right hand side vector (or PETSC_NULL) 364 365 366 Notes: 367 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 368 internally scaled, so this does nothing. For MPIROWBS it 369 permutes and diagonally scales. 370 371 The KSP methods automatically call this routine when required 372 (via PCPreSolve()) so it is rarely used directly. 373 374 Level: Developer 375 376 .seealso: MatUseScaledForm(), MatScaleSystem() 377 @*/ 378 PetscErrorCode PETSCMAT_DLLEXPORT MatUnScaleSystem(Mat mat,Vec x,Vec b) 379 { 380 PetscErrorCode ierr; 381 382 PetscFunctionBegin; 383 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 384 PetscValidType(mat,1); 385 ierr = MatPreallocated(mat);CHKERRQ(ierr); 386 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE,2);PetscCheckSameComm(mat,1,x,2);} 387 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE,3);PetscCheckSameComm(mat,1,b,3);} 388 if (mat->ops->unscalesystem) { 389 ierr = (*mat->ops->unscalesystem)(mat,x,b);CHKERRQ(ierr); 390 } 391 PetscFunctionReturn(0); 392 } 393 394 #undef __FUNCT__ 395 #define __FUNCT__ "MatUseScaledForm" 396 /*@C 397 MatUseScaledForm - For matrix storage formats that scale the 398 matrix (for example MPIRowBS matrices are diagonally scaled on 399 assembly) indicates matrix operations (MatMult() etc) are 400 applied using the scaled matrix. 401 402 Collective on Mat 403 404 Input Parameter: 405 + mat - the matrix 406 - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 407 applying the original matrix 408 409 Notes: 410 For scaled matrix formats, applying the original, unscaled matrix 411 will be slightly more expensive 412 413 Level: Developer 414 415 .seealso: MatScaleSystem(), MatUnScaleSystem() 416 @*/ 417 PetscErrorCode PETSCMAT_DLLEXPORT MatUseScaledForm(Mat mat,PetscTruth scaled) 418 { 419 PetscErrorCode ierr; 420 421 PetscFunctionBegin; 422 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 423 PetscValidType(mat,1); 424 ierr = MatPreallocated(mat);CHKERRQ(ierr); 425 if (mat->ops->usescaledform) { 426 ierr = (*mat->ops->usescaledform)(mat,scaled);CHKERRQ(ierr); 427 } 428 PetscFunctionReturn(0); 429 } 430 431 #undef __FUNCT__ 432 #define __FUNCT__ "MatDestroy" 433 /*@C 434 MatDestroy - Frees space taken by a matrix. 435 436 Collective on Mat 437 438 Input Parameter: 439 . A - the matrix 440 441 Level: beginner 442 443 @*/ 444 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroy(Mat A) 445 { 446 PetscErrorCode ierr; 447 448 PetscFunctionBegin; 449 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 450 PetscValidType(A,1); 451 ierr = MatPreallocated(A);CHKERRQ(ierr); 452 if (--A->refct > 0) PetscFunctionReturn(0); 453 454 /* if memory was published with AMS then destroy it */ 455 ierr = PetscObjectDepublish(A);CHKERRQ(ierr); 456 if (A->mapping) { 457 ierr = ISLocalToGlobalMappingDestroy(A->mapping);CHKERRQ(ierr); 458 } 459 if (A->bmapping) { 460 ierr = ISLocalToGlobalMappingDestroy(A->bmapping);CHKERRQ(ierr); 461 } 462 if (A->rmap) { 463 ierr = PetscMapDestroy(A->rmap);CHKERRQ(ierr); 464 } 465 if (A->cmap) { 466 ierr = PetscMapDestroy(A->cmap);CHKERRQ(ierr); 467 } 468 ierr = (*A->ops->destroy)(A);CHKERRQ(ierr); 469 ierr = PetscHeaderDestroy(A);CHKERRQ(ierr); 470 PetscFunctionReturn(0); 471 } 472 473 #undef __FUNCT__ 474 #define __FUNCT__ "MatValid" 475 /*@ 476 MatValid - Checks whether a matrix object is valid. 477 478 Collective on Mat 479 480 Input Parameter: 481 . m - the matrix to check 482 483 Output Parameter: 484 flg - flag indicating matrix status, either 485 PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise. 486 487 Level: developer 488 489 Concepts: matrices^validity 490 @*/ 491 PetscErrorCode PETSCMAT_DLLEXPORT MatValid(Mat m,PetscTruth *flg) 492 { 493 PetscFunctionBegin; 494 PetscValidIntPointer(flg,1); 495 if (!m) *flg = PETSC_FALSE; 496 else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE; 497 else *flg = PETSC_TRUE; 498 PetscFunctionReturn(0); 499 } 500 501 #undef __FUNCT__ 502 #define __FUNCT__ "MatSetValues" 503 /*@ 504 MatSetValues - Inserts or adds a block of values into a matrix. 505 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 506 MUST be called after all calls to MatSetValues() have been completed. 507 508 Not Collective 509 510 Input Parameters: 511 + mat - the matrix 512 . v - a logically two-dimensional array of values 513 . m, idxm - the number of rows and their global indices 514 . n, idxn - the number of columns and their global indices 515 - addv - either ADD_VALUES or INSERT_VALUES, where 516 ADD_VALUES adds values to any existing entries, and 517 INSERT_VALUES replaces existing entries with new values 518 519 Notes: 520 By default the values, v, are row-oriented and unsorted. 521 See MatSetOption() for other options. 522 523 Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 524 options cannot be mixed without intervening calls to the assembly 525 routines. 526 527 MatSetValues() uses 0-based row and column numbers in Fortran 528 as well as in C. 529 530 Negative indices may be passed in idxm and idxn, these rows and columns are 531 simply ignored. This allows easily inserting element stiffness matrices 532 with homogeneous Dirchlet boundary conditions that you don't want represented 533 in the matrix. 534 535 Efficiency Alert: 536 The routine MatSetValuesBlocked() may offer much better efficiency 537 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 538 539 Level: beginner 540 541 Concepts: matrices^putting entries in 542 543 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 544 InsertMode, INSERT_VALUES, ADD_VALUES 545 @*/ 546 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 547 { 548 PetscErrorCode ierr; 549 550 PetscFunctionBegin; 551 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 552 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 553 PetscValidType(mat,1); 554 PetscValidIntPointer(idxm,3); 555 PetscValidIntPointer(idxn,5); 556 PetscValidScalarPointer(v,6); 557 ierr = MatPreallocated(mat);CHKERRQ(ierr); 558 if (mat->insertmode == NOT_SET_VALUES) { 559 mat->insertmode = addv; 560 } 561 #if defined(PETSC_USE_DEBUG) 562 else if (mat->insertmode != addv) { 563 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 564 } 565 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 566 #endif 567 568 if (mat->assembled) { 569 mat->was_assembled = PETSC_TRUE; 570 mat->assembled = PETSC_FALSE; 571 } 572 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 573 if (!mat->ops->setvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 574 ierr = (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 575 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 576 PetscFunctionReturn(0); 577 } 578 579 #undef __FUNCT__ 580 #define __FUNCT__ "MatSetValuesStencil" 581 /*@C 582 MatSetValuesStencil - Inserts or adds a block of values into a matrix. 583 Using structured grid indexing 584 585 Not Collective 586 587 Input Parameters: 588 + mat - the matrix 589 . v - a logically two-dimensional array of values 590 . m - number of rows being entered 591 . idxm - grid coordinates (and component number when dof > 1) for matrix rows being entered 592 . n - number of columns being entered 593 . idxn - grid coordinates (and component number when dof > 1) for matrix columns being entered 594 - addv - either ADD_VALUES or INSERT_VALUES, where 595 ADD_VALUES adds values to any existing entries, and 596 INSERT_VALUES replaces existing entries with new values 597 598 Notes: 599 By default the values, v, are row-oriented and unsorted. 600 See MatSetOption() for other options. 601 602 Calls to MatSetValuesStencil() with the INSERT_VALUES and ADD_VALUES 603 options cannot be mixed without intervening calls to the assembly 604 routines. 605 606 The grid coordinates are across the entire grid, not just the local portion 607 608 MatSetValuesStencil() uses 0-based row and column numbers in Fortran 609 as well as in C. 610 611 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 612 613 In order to use this routine you must either obtain the matrix with DAGetMatrix() 614 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 615 616 The columns and rows in the stencil passed in MUST be contained within the 617 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 618 if you create a DA with an overlap of one grid level and on a particular process its first 619 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 620 first i index you can use in your column and row indices in MatSetStencil() is 5. 621 622 In Fortran idxm and idxn should be declared as 623 $ MatStencil idxm(4,m),idxn(4,n) 624 and the values inserted using 625 $ idxm(MatStencil_i,1) = i 626 $ idxm(MatStencil_j,1) = j 627 $ idxm(MatStencil_k,1) = k 628 $ idxm(MatStencil_c,1) = c 629 etc 630 631 Negative indices may be passed in idxm and idxn, these rows and columns are 632 simply ignored. This allows easily inserting element stiffness matrices 633 with homogeneous Dirchlet boundary conditions that you don't want represented 634 in the matrix. 635 636 Inspired by the structured grid interface to the HYPRE package 637 (http://www.llnl.gov/CASC/hypre) 638 639 Efficiency Alert: 640 The routine MatSetValuesBlockedStencil() may offer much better efficiency 641 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 642 643 Level: beginner 644 645 Concepts: matrices^putting entries in 646 647 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 648 MatSetValues(), MatSetValuesBlockedStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 649 @*/ 650 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 651 { 652 PetscErrorCode ierr; 653 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 654 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 655 656 PetscFunctionBegin; 657 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 658 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 659 PetscValidType(mat,1); 660 PetscValidIntPointer(idxm,3); 661 PetscValidIntPointer(idxn,5); 662 PetscValidScalarPointer(v,6); 663 664 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 665 if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 666 667 for (i=0; i<m; i++) { 668 for (j=0; j<3-sdim; j++) dxm++; 669 tmp = *dxm++ - starts[0]; 670 for (j=0; j<dim-1; j++) { 671 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 672 else tmp = tmp*dims[j] + dxm[-1] - starts[j+1]; 673 } 674 if (mat->stencil.noc) dxm++; 675 jdxm[i] = tmp; 676 } 677 for (i=0; i<n; i++) { 678 for (j=0; j<3-sdim; j++) dxn++; 679 tmp = *dxn++ - starts[0]; 680 for (j=0; j<dim-1; j++) { 681 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 682 else tmp = tmp*dims[j] + dxn[-1] - starts[j+1]; 683 } 684 if (mat->stencil.noc) dxn++; 685 jdxn[i] = tmp; 686 } 687 ierr = MatSetValuesLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 688 PetscFunctionReturn(0); 689 } 690 691 #undef __FUNCT__ 692 #define __FUNCT__ "MatSetValuesBlockedStencil" 693 /*@C 694 MatSetValuesBlockedStencil - Inserts or adds a block of values into a matrix. 695 Using structured grid indexing 696 697 Not Collective 698 699 Input Parameters: 700 + mat - the matrix 701 . v - a logically two-dimensional array of values 702 . m - number of rows being entered 703 . idxm - grid coordinates for matrix rows being entered 704 . n - number of columns being entered 705 . idxn - grid coordinates for matrix columns being entered 706 - addv - either ADD_VALUES or INSERT_VALUES, where 707 ADD_VALUES adds values to any existing entries, and 708 INSERT_VALUES replaces existing entries with new values 709 710 Notes: 711 By default the values, v, are row-oriented and unsorted. 712 See MatSetOption() for other options. 713 714 Calls to MatSetValuesBlockedStencil() with the INSERT_VALUES and ADD_VALUES 715 options cannot be mixed without intervening calls to the assembly 716 routines. 717 718 The grid coordinates are across the entire grid, not just the local portion 719 720 MatSetValuesBlockedStencil() uses 0-based row and column numbers in Fortran 721 as well as in C. 722 723 For setting/accessing vector values via array coordinates you can use the DAVecGetArray() routine 724 725 In order to use this routine you must either obtain the matrix with DAGetMatrix() 726 or call MatSetLocalToGlobalMapping() and MatSetStencil() first. 727 728 The columns and rows in the stencil passed in MUST be contained within the 729 ghost region of the given process as set with DACreateXXX() or MatSetStencil(). For example, 730 if you create a DA with an overlap of one grid level and on a particular process its first 731 local nonghost x logical coordinate is 6 (so its first ghost x logical coordinate is 5) the 732 first i index you can use in your column and row indices in MatSetStencil() is 5. 733 734 In Fortran idxm and idxn should be declared as 735 $ MatStencil idxm(4,m),idxn(4,n) 736 and the values inserted using 737 $ idxm(MatStencil_i,1) = i 738 $ idxm(MatStencil_j,1) = j 739 $ idxm(MatStencil_k,1) = k 740 etc 741 742 Negative indices may be passed in idxm and idxn, these rows and columns are 743 simply ignored. This allows easily inserting element stiffness matrices 744 with homogeneous Dirchlet boundary conditions that you don't want represented 745 in the matrix. 746 747 Inspired by the structured grid interface to the HYPRE package 748 (http://www.llnl.gov/CASC/hypre) 749 750 Level: beginner 751 752 Concepts: matrices^putting entries in 753 754 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 755 MatSetValues(), MatSetValuesStencil(), MatSetStencil(), DAGetMatrix(), DAVecGetArray(), MatStencil 756 @*/ 757 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedStencil(Mat mat,PetscInt m,const MatStencil idxm[],PetscInt n,const MatStencil idxn[],const PetscScalar v[],InsertMode addv) 758 { 759 PetscErrorCode ierr; 760 PetscInt j,i,jdxm[128],jdxn[256],dim = mat->stencil.dim,*dims = mat->stencil.dims+1,tmp; 761 PetscInt *starts = mat->stencil.starts,*dxm = (PetscInt*)idxm,*dxn = (PetscInt*)idxn,sdim = dim - (1 - (PetscInt)mat->stencil.noc); 762 763 PetscFunctionBegin; 764 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 765 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 766 PetscValidType(mat,1); 767 PetscValidIntPointer(idxm,3); 768 PetscValidIntPointer(idxn,5); 769 PetscValidScalarPointer(v,6); 770 771 if (m > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 128 rows at a time; trying to set %D",m); 772 if (n > 128) SETERRQ1(PETSC_ERR_SUP,"Can only set 256 columns at a time; trying to set %D",n); 773 774 for (i=0; i<m; i++) { 775 for (j=0; j<3-sdim; j++) dxm++; 776 tmp = *dxm++ - starts[0]; 777 for (j=0; j<sdim-1; j++) { 778 if ((*dxm++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 779 else tmp = tmp*dims[j] + dxm[-1] - starts[j+1]; 780 } 781 dxm++; 782 jdxm[i] = tmp; 783 } 784 for (i=0; i<n; i++) { 785 for (j=0; j<3-sdim; j++) dxn++; 786 tmp = *dxn++ - starts[0]; 787 for (j=0; j<sdim-1; j++) { 788 if ((*dxn++ - starts[j+1]) < 0 || tmp < 0) tmp = PETSC_MIN_INT; 789 else tmp = tmp*dims[j] + dxn[-1] - starts[j+1]; 790 } 791 dxn++; 792 jdxn[i] = tmp; 793 } 794 ierr = MatSetValuesBlockedLocal(mat,m,jdxm,n,jdxn,v,addv);CHKERRQ(ierr); 795 PetscFunctionReturn(0); 796 } 797 798 #undef __FUNCT__ 799 #define __FUNCT__ "MatSetStencil" 800 /*@ 801 MatSetStencil - Sets the grid information for setting values into a matrix via 802 MatSetValuesStencil() 803 804 Not Collective 805 806 Input Parameters: 807 + mat - the matrix 808 . dim - dimension of the grid 1, 2, or 3 809 . dims - number of grid points in x, y, and z direction, including ghost points on your processor 810 . starts - starting point of ghost nodes on your processor in x, y, and z direction 811 - dof - number of degrees of freedom per node 812 813 814 Inspired by the structured grid interface to the HYPRE package 815 (www.llnl.gov/CASC/hyper) 816 817 For matrices generated with DAGetMatrix() this routine is automatically called and so not needed by the 818 user. 819 820 Level: beginner 821 822 Concepts: matrices^putting entries in 823 824 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 825 MatSetValues(), MatSetValuesBlockedStencil(), MatSetValuesStencil() 826 @*/ 827 PetscErrorCode PETSCMAT_DLLEXPORT MatSetStencil(Mat mat,PetscInt dim,const PetscInt dims[],const PetscInt starts[],PetscInt dof) 828 { 829 PetscInt i; 830 831 PetscFunctionBegin; 832 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 833 PetscValidIntPointer(dims,3); 834 PetscValidIntPointer(starts,4); 835 836 mat->stencil.dim = dim + (dof > 1); 837 for (i=0; i<dim; i++) { 838 mat->stencil.dims[i] = dims[dim-i-1]; /* copy the values in backwards */ 839 mat->stencil.starts[i] = starts[dim-i-1]; 840 } 841 mat->stencil.dims[dim] = dof; 842 mat->stencil.starts[dim] = 0; 843 mat->stencil.noc = (PetscTruth)(dof == 1); 844 PetscFunctionReturn(0); 845 } 846 847 #undef __FUNCT__ 848 #define __FUNCT__ "MatSetValuesBlocked" 849 /*@ 850 MatSetValuesBlocked - Inserts or adds a block of values into a matrix. 851 852 Not Collective 853 854 Input Parameters: 855 + mat - the matrix 856 . v - a logically two-dimensional array of values 857 . m, idxm - the number of block rows and their global block indices 858 . n, idxn - the number of block columns and their global block indices 859 - addv - either ADD_VALUES or INSERT_VALUES, where 860 ADD_VALUES adds values to any existing entries, and 861 INSERT_VALUES replaces existing entries with new values 862 863 Notes: 864 By default the values, v, are row-oriented and unsorted. So the layout of 865 v is the same as for MatSetValues(). See MatSetOption() for other options. 866 867 Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 868 options cannot be mixed without intervening calls to the assembly 869 routines. 870 871 MatSetValuesBlocked() uses 0-based row and column numbers in Fortran 872 as well as in C. 873 874 Negative indices may be passed in idxm and idxn, these rows and columns are 875 simply ignored. This allows easily inserting element stiffness matrices 876 with homogeneous Dirchlet boundary conditions that you don't want represented 877 in the matrix. 878 879 Each time an entry is set within a sparse matrix via MatSetValues(), 880 internal searching must be done to determine where to place the the 881 data in the matrix storage space. By instead inserting blocks of 882 entries via MatSetValuesBlocked(), the overhead of matrix assembly is 883 reduced. 884 885 Restrictions: 886 MatSetValuesBlocked() is currently supported only for the BAIJ and SBAIJ formats 887 888 Level: intermediate 889 890 Concepts: matrices^putting entries in blocked 891 892 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal() 893 @*/ 894 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlocked(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],const PetscScalar v[],InsertMode addv) 895 { 896 PetscErrorCode ierr; 897 898 PetscFunctionBegin; 899 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 900 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 901 PetscValidType(mat,1); 902 PetscValidIntPointer(idxm,3); 903 PetscValidIntPointer(idxn,5); 904 PetscValidScalarPointer(v,6); 905 ierr = MatPreallocated(mat);CHKERRQ(ierr); 906 if (mat->insertmode == NOT_SET_VALUES) { 907 mat->insertmode = addv; 908 } 909 #if defined(PETSC_USE_DEBUG) 910 else if (mat->insertmode != addv) { 911 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 912 } 913 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 914 #endif 915 916 if (mat->assembled) { 917 mat->was_assembled = PETSC_TRUE; 918 mat->assembled = PETSC_FALSE; 919 } 920 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 921 if (!mat->ops->setvaluesblocked) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 922 ierr = (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 923 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 924 PetscFunctionReturn(0); 925 } 926 927 #undef __FUNCT__ 928 #define __FUNCT__ "MatGetValues" 929 /*@ 930 MatGetValues - Gets a block of values from a matrix. 931 932 Not Collective; currently only returns a local block 933 934 Input Parameters: 935 + mat - the matrix 936 . v - a logically two-dimensional array for storing the values 937 . m, idxm - the number of rows and their global indices 938 - n, idxn - the number of columns and their global indices 939 940 Notes: 941 The user must allocate space (m*n PetscScalars) for the values, v. 942 The values, v, are then returned in a row-oriented format, 943 analogous to that used by default in MatSetValues(). 944 945 MatGetValues() uses 0-based row and column numbers in 946 Fortran as well as in C. 947 948 MatGetValues() requires that the matrix has been assembled 949 with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to 950 MatSetValues() and MatGetValues() CANNOT be made in succession 951 without intermediate matrix assembly. 952 953 Level: advanced 954 955 Concepts: matrices^accessing values 956 957 .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues() 958 @*/ 959 PetscErrorCode PETSCMAT_DLLEXPORT MatGetValues(Mat mat,PetscInt m,const PetscInt idxm[],PetscInt n,const PetscInt idxn[],PetscScalar v[]) 960 { 961 PetscErrorCode ierr; 962 963 PetscFunctionBegin; 964 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 965 PetscValidType(mat,1); 966 PetscValidIntPointer(idxm,3); 967 PetscValidIntPointer(idxn,5); 968 PetscValidScalarPointer(v,6); 969 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 970 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 971 if (!mat->ops->getvalues) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 972 ierr = MatPreallocated(mat);CHKERRQ(ierr); 973 974 ierr = PetscLogEventBegin(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 975 ierr = (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);CHKERRQ(ierr); 976 ierr = PetscLogEventEnd(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 977 PetscFunctionReturn(0); 978 } 979 980 #undef __FUNCT__ 981 #define __FUNCT__ "MatSetLocalToGlobalMapping" 982 /*@ 983 MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by 984 the routine MatSetValuesLocal() to allow users to insert matrix entries 985 using a local (per-processor) numbering. 986 987 Not Collective 988 989 Input Parameters: 990 + x - the matrix 991 - mapping - mapping created with ISLocalToGlobalMappingCreate() 992 or ISLocalToGlobalMappingCreateIS() 993 994 Level: intermediate 995 996 Concepts: matrices^local to global mapping 997 Concepts: local to global mapping^for matrices 998 999 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal() 1000 @*/ 1001 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping) 1002 { 1003 PetscErrorCode ierr; 1004 PetscFunctionBegin; 1005 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1006 PetscValidType(x,1); 1007 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1008 if (x->mapping) { 1009 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1010 } 1011 ierr = MatPreallocated(x);CHKERRQ(ierr); 1012 1013 if (x->ops->setlocaltoglobalmapping) { 1014 ierr = (*x->ops->setlocaltoglobalmapping)(x,mapping);CHKERRQ(ierr); 1015 } else { 1016 x->mapping = mapping; 1017 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1018 } 1019 PetscFunctionReturn(0); 1020 } 1021 1022 #undef __FUNCT__ 1023 #define __FUNCT__ "MatSetLocalToGlobalMappingBlock" 1024 /*@ 1025 MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use 1026 by the routine MatSetValuesBlockedLocal() to allow users to insert matrix 1027 entries using a local (per-processor) numbering. 1028 1029 Not Collective 1030 1031 Input Parameters: 1032 + x - the matrix 1033 - mapping - mapping created with ISLocalToGlobalMappingCreate() or 1034 ISLocalToGlobalMappingCreateIS() 1035 1036 Level: intermediate 1037 1038 Concepts: matrices^local to global mapping blocked 1039 Concepts: local to global mapping^for matrices, blocked 1040 1041 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(), 1042 MatSetValuesBlocked(), MatSetValuesLocal() 1043 @*/ 1044 PetscErrorCode PETSCMAT_DLLEXPORT MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping) 1045 { 1046 PetscErrorCode ierr; 1047 PetscFunctionBegin; 1048 PetscValidHeaderSpecific(x,MAT_COOKIE,1); 1049 PetscValidType(x,1); 1050 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE,2); 1051 if (x->bmapping) { 1052 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 1053 } 1054 x->bmapping = mapping; 1055 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 1056 PetscFunctionReturn(0); 1057 } 1058 1059 #undef __FUNCT__ 1060 #define __FUNCT__ "MatSetValuesLocal" 1061 /*@ 1062 MatSetValuesLocal - Inserts or adds values into certain locations of a matrix, 1063 using a local ordering of the nodes. 1064 1065 Not Collective 1066 1067 Input Parameters: 1068 + x - the matrix 1069 . nrow, irow - number of rows and their local indices 1070 . ncol, icol - number of columns and their local indices 1071 . y - a logically two-dimensional array of values 1072 - addv - either INSERT_VALUES or ADD_VALUES, where 1073 ADD_VALUES adds values to any existing entries, and 1074 INSERT_VALUES replaces existing entries with new values 1075 1076 Notes: 1077 Before calling MatSetValuesLocal(), the user must first set the 1078 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 1079 1080 Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 1081 options cannot be mixed without intervening calls to the assembly 1082 routines. 1083 1084 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 1085 MUST be called after all calls to MatSetValuesLocal() have been completed. 1086 1087 Level: intermediate 1088 1089 Concepts: matrices^putting entries in with local numbering 1090 1091 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(), 1092 MatSetValueLocal() 1093 @*/ 1094 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv) 1095 { 1096 PetscErrorCode ierr; 1097 PetscInt irowm[2048],icolm[2048]; 1098 1099 PetscFunctionBegin; 1100 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1101 PetscValidType(mat,1); 1102 PetscValidIntPointer(irow,3); 1103 PetscValidIntPointer(icol,5); 1104 PetscValidScalarPointer(y,6); 1105 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1106 if (mat->insertmode == NOT_SET_VALUES) { 1107 mat->insertmode = addv; 1108 } 1109 #if defined(PETSC_USE_DEBUG) 1110 else if (mat->insertmode != addv) { 1111 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1112 } 1113 if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) { 1114 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol); 1115 } 1116 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1117 #endif 1118 1119 if (mat->assembled) { 1120 mat->was_assembled = PETSC_TRUE; 1121 mat->assembled = PETSC_FALSE; 1122 } 1123 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1124 if (!mat->ops->setvalueslocal) { 1125 ierr = ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);CHKERRQ(ierr); 1126 ierr = ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);CHKERRQ(ierr); 1127 ierr = (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 1128 } else { 1129 ierr = (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);CHKERRQ(ierr); 1130 } 1131 mat->same_nonzero = PETSC_FALSE; 1132 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1133 PetscFunctionReturn(0); 1134 } 1135 1136 #undef __FUNCT__ 1137 #define __FUNCT__ "MatSetValuesBlockedLocal" 1138 /*@ 1139 MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix, 1140 using a local ordering of the nodes a block at a time. 1141 1142 Not Collective 1143 1144 Input Parameters: 1145 + x - the matrix 1146 . nrow, irow - number of rows and their local indices 1147 . ncol, icol - number of columns and their local indices 1148 . y - a logically two-dimensional array of values 1149 - addv - either INSERT_VALUES or ADD_VALUES, where 1150 ADD_VALUES adds values to any existing entries, and 1151 INSERT_VALUES replaces existing entries with new values 1152 1153 Notes: 1154 Before calling MatSetValuesBlockedLocal(), the user must first set the 1155 local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(), 1156 where the mapping MUST be set for matrix blocks, not for matrix elements. 1157 1158 Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 1159 options cannot be mixed without intervening calls to the assembly 1160 routines. 1161 1162 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 1163 MUST be called after all calls to MatSetValuesBlockedLocal() have been completed. 1164 1165 Level: intermediate 1166 1167 Concepts: matrices^putting blocked values in with local numbering 1168 1169 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked() 1170 @*/ 1171 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesBlockedLocal(Mat mat,PetscInt nrow,const PetscInt irow[],PetscInt ncol,const PetscInt icol[],const PetscScalar y[],InsertMode addv) 1172 { 1173 PetscErrorCode ierr; 1174 PetscInt irowm[2048],icolm[2048]; 1175 1176 PetscFunctionBegin; 1177 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1178 PetscValidType(mat,1); 1179 PetscValidIntPointer(irow,3); 1180 PetscValidIntPointer(icol,5); 1181 PetscValidScalarPointer(y,6); 1182 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1183 if (mat->insertmode == NOT_SET_VALUES) { 1184 mat->insertmode = addv; 1185 } 1186 #if defined(PETSC_USE_DEBUG) 1187 else if (mat->insertmode != addv) { 1188 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 1189 } 1190 if (!mat->bmapping) { 1191 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()"); 1192 } 1193 if (nrow > 2048 || ncol > 2048) { 1194 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %D %D",nrow,ncol); 1195 } 1196 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1197 #endif 1198 1199 if (mat->assembled) { 1200 mat->was_assembled = PETSC_TRUE; 1201 mat->assembled = PETSC_FALSE; 1202 } 1203 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1204 ierr = ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);CHKERRQ(ierr); 1205 ierr = ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);CHKERRQ(ierr); 1206 ierr = (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 1207 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 1208 PetscFunctionReturn(0); 1209 } 1210 1211 /* --------------------------------------------------------*/ 1212 #undef __FUNCT__ 1213 #define __FUNCT__ "MatMult" 1214 /*@ 1215 MatMult - Computes the matrix-vector product, y = Ax. 1216 1217 Collective on Mat and Vec 1218 1219 Input Parameters: 1220 + mat - the matrix 1221 - x - the vector to be multiplied 1222 1223 Output Parameters: 1224 . y - the result 1225 1226 Notes: 1227 The vectors x and y cannot be the same. I.e., one cannot 1228 call MatMult(A,y,y). 1229 1230 Level: beginner 1231 1232 Concepts: matrix-vector product 1233 1234 .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd() 1235 @*/ 1236 PetscErrorCode PETSCMAT_DLLEXPORT MatMult(Mat mat,Vec x,Vec y) 1237 { 1238 PetscErrorCode ierr; 1239 1240 PetscFunctionBegin; 1241 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1242 PetscValidType(mat,1); 1243 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1244 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1245 1246 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1247 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1248 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1249 #ifndef PETSC_HAVE_CONSTRAINTS 1250 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1251 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1252 if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n); 1253 #endif 1254 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1255 1256 if (mat->nullsp) { 1257 ierr = MatNullSpaceRemove(mat->nullsp,x,&x);CHKERRQ(ierr); 1258 } 1259 1260 ierr = PetscLogEventBegin(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 1261 ierr = (*mat->ops->mult)(mat,x,y);CHKERRQ(ierr); 1262 ierr = PetscLogEventEnd(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 1263 1264 if (mat->nullsp) { 1265 ierr = MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);CHKERRQ(ierr); 1266 } 1267 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1268 PetscFunctionReturn(0); 1269 } 1270 1271 #undef __FUNCT__ 1272 #define __FUNCT__ "MatMultTranspose" 1273 /*@ 1274 MatMultTranspose - Computes matrix transpose times a vector. 1275 1276 Collective on Mat and Vec 1277 1278 Input Parameters: 1279 + mat - the matrix 1280 - x - the vector to be multilplied 1281 1282 Output Parameters: 1283 . y - the result 1284 1285 Notes: 1286 The vectors x and y cannot be the same. I.e., one cannot 1287 call MatMultTranspose(A,y,y). 1288 1289 Level: beginner 1290 1291 Concepts: matrix vector product^transpose 1292 1293 .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd() 1294 @*/ 1295 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTranspose(Mat mat,Vec x,Vec y) 1296 { 1297 PetscErrorCode ierr; 1298 PetscTruth flg1, flg2; 1299 1300 PetscFunctionBegin; 1301 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1302 PetscValidType(mat,1); 1303 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1304 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1305 1306 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1307 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1308 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1309 #ifndef PETSC_HAVE_CONSTRAINTS 1310 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 1311 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N); 1312 #endif 1313 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1314 1315 if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP, "Operation not supported"); 1316 ierr = PetscLogEventBegin(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1317 if (!mat->ops->multtranspose) SETERRQ(PETSC_ERR_SUP,"This matrix type does not have a multiply tranpose defined"); 1318 1319 ierr = PetscTypeCompare((PetscObject)mat,MATSEQSBAIJ,&flg1); 1320 ierr = PetscTypeCompare((PetscObject)mat,MATMPISBAIJ,&flg2); 1321 if (flg1 || flg2) { /* mat is in sbaij format */ 1322 ierr = (*mat->ops->mult)(mat,x,y);CHKERRQ(ierr); 1323 } else { 1324 ierr = (*mat->ops->multtranspose)(mat,x,y);CHKERRQ(ierr); 1325 } 1326 ierr = PetscLogEventEnd(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1327 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1328 PetscFunctionReturn(0); 1329 } 1330 1331 #undef __FUNCT__ 1332 #define __FUNCT__ "MatMultAdd" 1333 /*@ 1334 MatMultAdd - Computes v3 = v2 + A * v1. 1335 1336 Collective on Mat and Vec 1337 1338 Input Parameters: 1339 + mat - the matrix 1340 - v1, v2 - the vectors 1341 1342 Output Parameters: 1343 . v3 - the result 1344 1345 Notes: 1346 The vectors v1 and v3 cannot be the same. I.e., one cannot 1347 call MatMultAdd(A,v1,v2,v1). 1348 1349 Level: beginner 1350 1351 Concepts: matrix vector product^addition 1352 1353 .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd() 1354 @*/ 1355 PetscErrorCode PETSCMAT_DLLEXPORT MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1356 { 1357 PetscErrorCode ierr; 1358 1359 PetscFunctionBegin; 1360 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1361 PetscValidType(mat,1); 1362 PetscValidHeaderSpecific(v1,VEC_COOKIE,2); 1363 PetscValidHeaderSpecific(v2,VEC_COOKIE,3); 1364 PetscValidHeaderSpecific(v3,VEC_COOKIE,4); 1365 1366 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1367 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1368 if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->N,v1->N); 1369 if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->M,v2->N); 1370 if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->M,v3->N); 1371 if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %D %D",mat->m,v3->n); 1372 if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %D %D",mat->m,v2->n); 1373 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1374 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1375 1376 ierr = PetscLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1377 ierr = (*mat->ops->multadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1378 ierr = PetscLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1379 ierr = PetscObjectStateIncrease((PetscObject)v3);CHKERRQ(ierr); 1380 PetscFunctionReturn(0); 1381 } 1382 1383 #undef __FUNCT__ 1384 #define __FUNCT__ "MatMultTransposeAdd" 1385 /*@ 1386 MatMultTransposeAdd - Computes v3 = v2 + A' * v1. 1387 1388 Collective on Mat and Vec 1389 1390 Input Parameters: 1391 + mat - the matrix 1392 - v1, v2 - the vectors 1393 1394 Output Parameters: 1395 . v3 - the result 1396 1397 Notes: 1398 The vectors v1 and v3 cannot be the same. I.e., one cannot 1399 call MatMultTransposeAdd(A,v1,v2,v1). 1400 1401 Level: beginner 1402 1403 Concepts: matrix vector product^transpose and addition 1404 1405 .seealso: MatMultTranspose(), MatMultAdd(), MatMult() 1406 @*/ 1407 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1408 { 1409 PetscErrorCode ierr; 1410 1411 PetscFunctionBegin; 1412 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1413 PetscValidType(mat,1); 1414 PetscValidHeaderSpecific(v1,VEC_COOKIE,2); 1415 PetscValidHeaderSpecific(v2,VEC_COOKIE,3); 1416 PetscValidHeaderSpecific(v3,VEC_COOKIE,4); 1417 1418 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1419 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1420 if (!mat->ops->multtransposeadd) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1421 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1422 if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %D %D",mat->M,v1->N); 1423 if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %D %D",mat->N,v2->N); 1424 if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %D %D",mat->N,v3->N); 1425 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1426 1427 ierr = PetscLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1428 ierr = (*mat->ops->multtransposeadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1429 ierr = PetscLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1430 ierr = PetscObjectStateIncrease((PetscObject)v3);CHKERRQ(ierr); 1431 PetscFunctionReturn(0); 1432 } 1433 1434 #undef __FUNCT__ 1435 #define __FUNCT__ "MatMultConstrained" 1436 /*@ 1437 MatMultConstrained - The inner multiplication routine for a 1438 constrained matrix P^T A P. 1439 1440 Collective on Mat and Vec 1441 1442 Input Parameters: 1443 + mat - the matrix 1444 - x - the vector to be multilplied 1445 1446 Output Parameters: 1447 . y - the result 1448 1449 Notes: 1450 The vectors x and y cannot be the same. I.e., one cannot 1451 call MatMult(A,y,y). 1452 1453 Level: beginner 1454 1455 .keywords: matrix, multiply, matrix-vector product, constraint 1456 .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd() 1457 @*/ 1458 PetscErrorCode PETSCMAT_DLLEXPORT MatMultConstrained(Mat mat,Vec x,Vec y) 1459 { 1460 PetscErrorCode ierr; 1461 1462 PetscFunctionBegin; 1463 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1464 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1465 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1466 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1467 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1468 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1469 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1470 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1471 if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %D %D",mat->m,y->n); 1472 1473 ierr = PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1474 ierr = (*mat->ops->multconstrained)(mat,x,y);CHKERRQ(ierr); 1475 ierr = PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1476 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1477 1478 PetscFunctionReturn(0); 1479 } 1480 1481 #undef __FUNCT__ 1482 #define __FUNCT__ "MatMultTransposeConstrained" 1483 /*@ 1484 MatMultTransposeConstrained - The inner multiplication routine for a 1485 constrained matrix P^T A^T P. 1486 1487 Collective on Mat and Vec 1488 1489 Input Parameters: 1490 + mat - the matrix 1491 - x - the vector to be multilplied 1492 1493 Output Parameters: 1494 . y - the result 1495 1496 Notes: 1497 The vectors x and y cannot be the same. I.e., one cannot 1498 call MatMult(A,y,y). 1499 1500 Level: beginner 1501 1502 .keywords: matrix, multiply, matrix-vector product, constraint 1503 .seealso: MatMult(), MatMultTrans(), MatMultAdd(), MatMultTransAdd() 1504 @*/ 1505 PetscErrorCode PETSCMAT_DLLEXPORT MatMultTransposeConstrained(Mat mat,Vec x,Vec y) 1506 { 1507 PetscErrorCode ierr; 1508 1509 PetscFunctionBegin; 1510 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1511 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 1512 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 1513 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1514 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1515 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1516 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 1517 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 1518 1519 ierr = PetscLogEventBegin(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1520 ierr = (*mat->ops->multtransposeconstrained)(mat,x,y);CHKERRQ(ierr); 1521 ierr = PetscLogEventEnd(MAT_MultConstrained,mat,x,y,0);CHKERRQ(ierr); 1522 ierr = PetscObjectStateIncrease((PetscObject)y);CHKERRQ(ierr); 1523 1524 PetscFunctionReturn(0); 1525 } 1526 /* ------------------------------------------------------------*/ 1527 #undef __FUNCT__ 1528 #define __FUNCT__ "MatGetInfo" 1529 /*@C 1530 MatGetInfo - Returns information about matrix storage (number of 1531 nonzeros, memory, etc.). 1532 1533 Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used 1534 as the flag 1535 1536 Input Parameters: 1537 . mat - the matrix 1538 1539 Output Parameters: 1540 + flag - flag indicating the type of parameters to be returned 1541 (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors, 1542 MAT_GLOBAL_SUM - sum over all processors) 1543 - info - matrix information context 1544 1545 Notes: 1546 The MatInfo context contains a variety of matrix data, including 1547 number of nonzeros allocated and used, number of mallocs during 1548 matrix assembly, etc. Additional information for factored matrices 1549 is provided (such as the fill ratio, number of mallocs during 1550 factorization, etc.). Much of this info is printed to STDOUT 1551 when using the runtime options 1552 $ -log_info -mat_view_info 1553 1554 Example for C/C++ Users: 1555 See the file ${PETSC_DIR}/include/petscmat.h for a complete list of 1556 data within the MatInfo context. For example, 1557 .vb 1558 MatInfo info; 1559 Mat A; 1560 double mal, nz_a, nz_u; 1561 1562 MatGetInfo(A,MAT_LOCAL,&info); 1563 mal = info.mallocs; 1564 nz_a = info.nz_allocated; 1565 .ve 1566 1567 Example for Fortran Users: 1568 Fortran users should declare info as a double precision 1569 array of dimension MAT_INFO_SIZE, and then extract the parameters 1570 of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h 1571 a complete list of parameter names. 1572 .vb 1573 double precision info(MAT_INFO_SIZE) 1574 double precision mal, nz_a 1575 Mat A 1576 integer ierr 1577 1578 call MatGetInfo(A,MAT_LOCAL,info,ierr) 1579 mal = info(MAT_INFO_MALLOCS) 1580 nz_a = info(MAT_INFO_NZ_ALLOCATED) 1581 .ve 1582 1583 Level: intermediate 1584 1585 Concepts: matrices^getting information on 1586 1587 @*/ 1588 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info) 1589 { 1590 PetscErrorCode ierr; 1591 1592 PetscFunctionBegin; 1593 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1594 PetscValidType(mat,1); 1595 PetscValidPointer(info,3); 1596 if (!mat->ops->getinfo) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1597 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1598 ierr = (*mat->ops->getinfo)(mat,flag,info);CHKERRQ(ierr); 1599 PetscFunctionReturn(0); 1600 } 1601 1602 /* ----------------------------------------------------------*/ 1603 #undef __FUNCT__ 1604 #define __FUNCT__ "MatILUDTFactor" 1605 /*@C 1606 MatILUDTFactor - Performs a drop tolerance ILU factorization. 1607 1608 Collective on Mat 1609 1610 Input Parameters: 1611 + mat - the matrix 1612 . row - row permutation 1613 . col - column permutation 1614 - info - information about the factorization to be done 1615 1616 Output Parameters: 1617 . fact - the factored matrix 1618 1619 Level: developer 1620 1621 Notes: 1622 Most users should employ the simplified KSP interface for linear solvers 1623 instead of working directly with matrix algebra routines such as this. 1624 See, e.g., KSPCreate(). 1625 1626 This is currently only supported for the SeqAIJ matrix format using code 1627 from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or 1628 Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright 1629 and thus can be distributed with PETSc. 1630 1631 Concepts: matrices^ILUDT factorization 1632 1633 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 1634 @*/ 1635 PetscErrorCode PETSCMAT_DLLEXPORT MatILUDTFactor(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 1636 { 1637 PetscErrorCode ierr; 1638 1639 PetscFunctionBegin; 1640 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1641 PetscValidType(mat,1); 1642 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 1643 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 1644 PetscValidPointer(info,4); 1645 PetscValidPointer(fact,5); 1646 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1647 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1648 if (!mat->ops->iludtfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1649 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1650 ierr = PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1651 ierr = (*mat->ops->iludtfactor)(mat,row,col,info,fact);CHKERRQ(ierr); 1652 ierr = PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1653 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 1654 1655 PetscFunctionReturn(0); 1656 } 1657 1658 #undef __FUNCT__ 1659 #define __FUNCT__ "MatLUFactor" 1660 /*@ 1661 MatLUFactor - Performs in-place LU factorization of matrix. 1662 1663 Collective on Mat 1664 1665 Input Parameters: 1666 + mat - the matrix 1667 . row - row permutation 1668 . col - column permutation 1669 - info - options for factorization, includes 1670 $ fill - expected fill as ratio of original fill. 1671 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 1672 $ Run with the option -log_info to determine an optimal value to use 1673 1674 Notes: 1675 Most users should employ the simplified KSP interface for linear solvers 1676 instead of working directly with matrix algebra routines such as this. 1677 See, e.g., KSPCreate(). 1678 1679 This changes the state of the matrix to a factored matrix; it cannot be used 1680 for example with MatSetValues() unless one first calls MatSetUnfactored(). 1681 1682 Level: developer 1683 1684 Concepts: matrices^LU factorization 1685 1686 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), 1687 MatGetOrdering(), MatSetUnfactored(), MatFactorInfo 1688 1689 @*/ 1690 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactor(Mat mat,IS row,IS col,MatFactorInfo *info) 1691 { 1692 PetscErrorCode ierr; 1693 1694 PetscFunctionBegin; 1695 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1696 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 1697 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 1698 PetscValidPointer(info,4); 1699 PetscValidType(mat,1); 1700 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1701 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1702 if (!mat->ops->lufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1703 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1704 1705 ierr = PetscLogEventBegin(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 1706 ierr = (*mat->ops->lufactor)(mat,row,col,info);CHKERRQ(ierr); 1707 ierr = PetscLogEventEnd(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 1708 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 1709 PetscFunctionReturn(0); 1710 } 1711 1712 #undef __FUNCT__ 1713 #define __FUNCT__ "MatILUFactor" 1714 /*@ 1715 MatILUFactor - Performs in-place ILU factorization of matrix. 1716 1717 Collective on Mat 1718 1719 Input Parameters: 1720 + mat - the matrix 1721 . row - row permutation 1722 . col - column permutation 1723 - info - structure containing 1724 $ levels - number of levels of fill. 1725 $ expected fill - as ratio of original fill. 1726 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 1727 missing diagonal entries) 1728 1729 Notes: 1730 Probably really in-place only when level of fill is zero, otherwise allocates 1731 new space to store factored matrix and deletes previous memory. 1732 1733 Most users should employ the simplified KSP interface for linear solvers 1734 instead of working directly with matrix algebra routines such as this. 1735 See, e.g., KSPCreate(). 1736 1737 Level: developer 1738 1739 Concepts: matrices^ILU factorization 1740 1741 .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 1742 @*/ 1743 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactor(Mat mat,IS row,IS col,MatFactorInfo *info) 1744 { 1745 PetscErrorCode ierr; 1746 1747 PetscFunctionBegin; 1748 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1749 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 1750 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 1751 PetscValidPointer(info,4); 1752 PetscValidType(mat,1); 1753 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 1754 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1755 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1756 if (!mat->ops->ilufactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1757 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1758 1759 ierr = PetscLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1760 ierr = (*mat->ops->ilufactor)(mat,row,col,info);CHKERRQ(ierr); 1761 ierr = PetscLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1762 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 1763 PetscFunctionReturn(0); 1764 } 1765 1766 #undef __FUNCT__ 1767 #define __FUNCT__ "MatLUFactorSymbolic" 1768 /*@ 1769 MatLUFactorSymbolic - Performs symbolic LU factorization of matrix. 1770 Call this routine before calling MatLUFactorNumeric(). 1771 1772 Collective on Mat 1773 1774 Input Parameters: 1775 + mat - the matrix 1776 . row, col - row and column permutations 1777 - info - options for factorization, includes 1778 $ fill - expected fill as ratio of original fill. 1779 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 1780 $ Run with the option -log_info to determine an optimal value to use 1781 1782 Output Parameter: 1783 . fact - new matrix that has been symbolically factored 1784 1785 Notes: 1786 See the users manual for additional information about 1787 choosing the fill factor for better efficiency. 1788 1789 Most users should employ the simplified KSP interface for linear solvers 1790 instead of working directly with matrix algebra routines such as this. 1791 See, e.g., KSPCreate(). 1792 1793 Level: developer 1794 1795 Concepts: matrices^LU symbolic factorization 1796 1797 .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 1798 @*/ 1799 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 1800 { 1801 PetscErrorCode ierr; 1802 1803 PetscFunctionBegin; 1804 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1805 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 1806 if (col) PetscValidHeaderSpecific(col,IS_COOKIE,3); 1807 PetscValidPointer(info,4); 1808 PetscValidType(mat,1); 1809 PetscValidPointer(fact,5); 1810 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1811 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1812 if (!mat->ops->lufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic LU",mat->type_name); 1813 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1814 1815 ierr = PetscLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 1816 ierr = (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 1817 ierr = PetscLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 1818 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 1819 PetscFunctionReturn(0); 1820 } 1821 1822 #undef __FUNCT__ 1823 #define __FUNCT__ "MatLUFactorNumeric" 1824 /*@ 1825 MatLUFactorNumeric - Performs numeric LU factorization of a matrix. 1826 Call this routine after first calling MatLUFactorSymbolic(). 1827 1828 Collective on Mat 1829 1830 Input Parameters: 1831 + mat - the matrix 1832 . info - options for factorization 1833 - fact - the matrix generated for the factor, from MatLUFactorSymbolic() 1834 1835 Notes: 1836 See MatLUFactor() for in-place factorization. See 1837 MatCholeskyFactorNumeric() for the symmetric, positive definite case. 1838 1839 Most users should employ the simplified KSP interface for linear solvers 1840 instead of working directly with matrix algebra routines such as this. 1841 See, e.g., KSPCreate(). 1842 1843 Level: developer 1844 1845 Concepts: matrices^LU numeric factorization 1846 1847 .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor() 1848 @*/ 1849 PetscErrorCode PETSCMAT_DLLEXPORT MatLUFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact) 1850 { 1851 PetscErrorCode ierr; 1852 1853 PetscFunctionBegin; 1854 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1855 PetscValidType(mat,1); 1856 PetscValidPointer(fact,2); 1857 PetscValidHeaderSpecific(*fact,MAT_COOKIE,2); 1858 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1859 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 1860 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %D should = %D %D should = %D", 1861 mat->M,(*fact)->M,mat->N,(*fact)->N); 1862 } 1863 if (!(*fact)->ops->lufactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1864 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1865 ierr = PetscLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1866 ierr = (*(*fact)->ops->lufactornumeric)(mat,info,fact);CHKERRQ(ierr); 1867 ierr = PetscLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1868 1869 ierr = MatView_Private(*fact);CHKERRQ(ierr); 1870 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 1871 PetscFunctionReturn(0); 1872 } 1873 1874 #undef __FUNCT__ 1875 #define __FUNCT__ "MatCholeskyFactor" 1876 /*@ 1877 MatCholeskyFactor - Performs in-place Cholesky factorization of a 1878 symmetric matrix. 1879 1880 Collective on Mat 1881 1882 Input Parameters: 1883 + mat - the matrix 1884 . perm - row and column permutations 1885 - f - expected fill as ratio of original fill 1886 1887 Notes: 1888 See MatLUFactor() for the nonsymmetric case. See also 1889 MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric(). 1890 1891 Most users should employ the simplified KSP interface for linear solvers 1892 instead of working directly with matrix algebra routines such as this. 1893 See, e.g., KSPCreate(). 1894 1895 Level: developer 1896 1897 Concepts: matrices^Cholesky factorization 1898 1899 .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric() 1900 MatGetOrdering() 1901 1902 @*/ 1903 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactor(Mat mat,IS perm,MatFactorInfo *info) 1904 { 1905 PetscErrorCode ierr; 1906 1907 PetscFunctionBegin; 1908 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1909 PetscValidType(mat,1); 1910 PetscValidHeaderSpecific(perm,IS_COOKIE,2); 1911 PetscValidPointer(info,3); 1912 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 1913 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1914 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1915 if (!mat->ops->choleskyfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1916 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1917 1918 ierr = PetscLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 1919 ierr = (*mat->ops->choleskyfactor)(mat,perm,info);CHKERRQ(ierr); 1920 ierr = PetscLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 1921 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 1922 PetscFunctionReturn(0); 1923 } 1924 1925 #undef __FUNCT__ 1926 #define __FUNCT__ "MatCholeskyFactorSymbolic" 1927 /*@ 1928 MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization 1929 of a symmetric matrix. 1930 1931 Collective on Mat 1932 1933 Input Parameters: 1934 + mat - the matrix 1935 . perm - row and column permutations 1936 - info - options for factorization, includes 1937 $ fill - expected fill as ratio of original fill. 1938 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 1939 $ Run with the option -log_info to determine an optimal value to use 1940 1941 Output Parameter: 1942 . fact - the factored matrix 1943 1944 Notes: 1945 See MatLUFactorSymbolic() for the nonsymmetric case. See also 1946 MatCholeskyFactor() and MatCholeskyFactorNumeric(). 1947 1948 Most users should employ the simplified KSP interface for linear solvers 1949 instead of working directly with matrix algebra routines such as this. 1950 See, e.g., KSPCreate(). 1951 1952 Level: developer 1953 1954 Concepts: matrices^Cholesky symbolic factorization 1955 1956 .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric() 1957 MatGetOrdering() 1958 1959 @*/ 1960 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact) 1961 { 1962 PetscErrorCode ierr; 1963 1964 PetscFunctionBegin; 1965 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 1966 PetscValidType(mat,1); 1967 if (perm) PetscValidHeaderSpecific(perm,IS_COOKIE,2); 1968 PetscValidPointer(info,3); 1969 PetscValidPointer(fact,4); 1970 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 1971 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1972 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1973 if (!mat->ops->choleskyfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 1974 ierr = MatPreallocated(mat);CHKERRQ(ierr); 1975 1976 ierr = PetscLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 1977 ierr = (*mat->ops->choleskyfactorsymbolic)(mat,perm,info,fact);CHKERRQ(ierr); 1978 ierr = PetscLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 1979 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 1980 PetscFunctionReturn(0); 1981 } 1982 1983 #undef __FUNCT__ 1984 #define __FUNCT__ "MatCholeskyFactorNumeric" 1985 /*@ 1986 MatCholeskyFactorNumeric - Performs numeric Cholesky factorization 1987 of a symmetric matrix. Call this routine after first calling 1988 MatCholeskyFactorSymbolic(). 1989 1990 Collective on Mat 1991 1992 Input Parameter: 1993 . mat - the initial matrix 1994 . info - options for factorization 1995 - fact - the symbolic factor of mat 1996 1997 Output Parameter: 1998 . fact - the factored matrix 1999 2000 Notes: 2001 Most users should employ the simplified KSP interface for linear solvers 2002 instead of working directly with matrix algebra routines such as this. 2003 See, e.g., KSPCreate(). 2004 2005 Level: developer 2006 2007 Concepts: matrices^Cholesky numeric factorization 2008 2009 .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric() 2010 @*/ 2011 PetscErrorCode PETSCMAT_DLLEXPORT MatCholeskyFactorNumeric(Mat mat,MatFactorInfo *info,Mat *fact) 2012 { 2013 PetscErrorCode ierr; 2014 2015 PetscFunctionBegin; 2016 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2017 PetscValidType(mat,1); 2018 PetscValidPointer(fact,2); 2019 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2020 if (!(*fact)->ops->choleskyfactornumeric) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2021 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 2022 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %D should = %D %D should = %D",mat->M,(*fact)->M,mat->N,(*fact)->N); 2023 } 2024 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2025 2026 ierr = PetscLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2027 ierr = (*(*fact)->ops->choleskyfactornumeric)(mat,info,fact);CHKERRQ(ierr); 2028 ierr = PetscLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 2029 ierr = PetscObjectStateIncrease((PetscObject)*fact);CHKERRQ(ierr); 2030 PetscFunctionReturn(0); 2031 } 2032 2033 /* ----------------------------------------------------------------*/ 2034 #undef __FUNCT__ 2035 #define __FUNCT__ "MatSolve" 2036 /*@ 2037 MatSolve - Solves A x = b, given a factored matrix. 2038 2039 Collective on Mat and Vec 2040 2041 Input Parameters: 2042 + mat - the factored matrix 2043 - b - the right-hand-side vector 2044 2045 Output Parameter: 2046 . x - the result vector 2047 2048 Notes: 2049 The vectors b and x cannot be the same. I.e., one cannot 2050 call MatSolve(A,x,x). 2051 2052 Notes: 2053 Most users should employ the simplified KSP interface for linear solvers 2054 instead of working directly with matrix algebra routines such as this. 2055 See, e.g., KSPCreate(). 2056 2057 Level: developer 2058 2059 Concepts: matrices^triangular solves 2060 2061 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd() 2062 @*/ 2063 PetscErrorCode PETSCMAT_DLLEXPORT MatSolve(Mat mat,Vec b,Vec x) 2064 { 2065 PetscErrorCode ierr; 2066 2067 PetscFunctionBegin; 2068 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2069 PetscValidType(mat,1); 2070 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2071 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2072 PetscCheckSameComm(mat,1,b,2); 2073 PetscCheckSameComm(mat,1,x,3); 2074 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2075 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2076 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2077 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2078 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2079 if (!mat->M && !mat->N) PetscFunctionReturn(0); 2080 if (!mat->ops->solve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2081 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2082 2083 ierr = PetscLogEventBegin(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2084 ierr = (*mat->ops->solve)(mat,b,x);CHKERRQ(ierr); 2085 ierr = PetscLogEventEnd(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 2086 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2087 PetscFunctionReturn(0); 2088 } 2089 2090 #undef __FUNCT__ 2091 #define __FUNCT__ "MatForwardSolve" 2092 /* @ 2093 MatForwardSolve - Solves L x = b, given a factored matrix, A = LU. 2094 2095 Collective on Mat and Vec 2096 2097 Input Parameters: 2098 + mat - the factored matrix 2099 - b - the right-hand-side vector 2100 2101 Output Parameter: 2102 . x - the result vector 2103 2104 Notes: 2105 MatSolve() should be used for most applications, as it performs 2106 a forward solve followed by a backward solve. 2107 2108 The vectors b and x cannot be the same. I.e., one cannot 2109 call MatForwardSolve(A,x,x). 2110 2111 Most users should employ the simplified KSP interface for linear solvers 2112 instead of working directly with matrix algebra routines such as this. 2113 See, e.g., KSPCreate(). 2114 2115 Level: developer 2116 2117 Concepts: matrices^forward solves 2118 2119 .seealso: MatSolve(), MatBackwardSolve() 2120 @ */ 2121 PetscErrorCode PETSCMAT_DLLEXPORT MatForwardSolve(Mat mat,Vec b,Vec x) 2122 { 2123 PetscErrorCode ierr; 2124 2125 PetscFunctionBegin; 2126 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2127 PetscValidType(mat,1); 2128 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2129 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2130 PetscCheckSameComm(mat,1,b,2); 2131 PetscCheckSameComm(mat,1,x,3); 2132 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2133 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2134 if (!mat->ops->forwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2135 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2136 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2137 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2138 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2139 ierr = PetscLogEventBegin(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2140 ierr = (*mat->ops->forwardsolve)(mat,b,x);CHKERRQ(ierr); 2141 ierr = PetscLogEventEnd(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 2142 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2143 PetscFunctionReturn(0); 2144 } 2145 2146 #undef __FUNCT__ 2147 #define __FUNCT__ "MatBackwardSolve" 2148 /* @ 2149 MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU. 2150 2151 Collective on Mat and Vec 2152 2153 Input Parameters: 2154 + mat - the factored matrix 2155 - b - the right-hand-side vector 2156 2157 Output Parameter: 2158 . x - the result vector 2159 2160 Notes: 2161 MatSolve() should be used for most applications, as it performs 2162 a forward solve followed by a backward solve. 2163 2164 The vectors b and x cannot be the same. I.e., one cannot 2165 call MatBackwardSolve(A,x,x). 2166 2167 Most users should employ the simplified KSP interface for linear solvers 2168 instead of working directly with matrix algebra routines such as this. 2169 See, e.g., KSPCreate(). 2170 2171 Level: developer 2172 2173 Concepts: matrices^backward solves 2174 2175 .seealso: MatSolve(), MatForwardSolve() 2176 @ */ 2177 PetscErrorCode PETSCMAT_DLLEXPORT MatBackwardSolve(Mat mat,Vec b,Vec x) 2178 { 2179 PetscErrorCode ierr; 2180 2181 PetscFunctionBegin; 2182 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2183 PetscValidType(mat,1); 2184 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2185 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2186 PetscCheckSameComm(mat,1,b,2); 2187 PetscCheckSameComm(mat,1,x,3); 2188 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2189 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2190 if (!mat->ops->backwardsolve) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2191 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2192 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2193 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2194 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2195 2196 ierr = PetscLogEventBegin(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2197 ierr = (*mat->ops->backwardsolve)(mat,b,x);CHKERRQ(ierr); 2198 ierr = PetscLogEventEnd(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 2199 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2200 PetscFunctionReturn(0); 2201 } 2202 2203 #undef __FUNCT__ 2204 #define __FUNCT__ "MatSolveAdd" 2205 /*@ 2206 MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix. 2207 2208 Collective on Mat and Vec 2209 2210 Input Parameters: 2211 + mat - the factored matrix 2212 . b - the right-hand-side vector 2213 - y - the vector to be added to 2214 2215 Output Parameter: 2216 . x - the result vector 2217 2218 Notes: 2219 The vectors b and x cannot be the same. I.e., one cannot 2220 call MatSolveAdd(A,x,y,x). 2221 2222 Most users should employ the simplified KSP interface for linear solvers 2223 instead of working directly with matrix algebra routines such as this. 2224 See, e.g., KSPCreate(). 2225 2226 Level: developer 2227 2228 Concepts: matrices^triangular solves 2229 2230 .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd() 2231 @*/ 2232 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveAdd(Mat mat,Vec b,Vec y,Vec x) 2233 { 2234 PetscScalar one = 1.0; 2235 Vec tmp; 2236 PetscErrorCode ierr; 2237 2238 PetscFunctionBegin; 2239 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2240 PetscValidType(mat,1); 2241 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2242 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2243 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2244 PetscCheckSameComm(mat,1,b,2); 2245 PetscCheckSameComm(mat,1,y,2); 2246 PetscCheckSameComm(mat,1,x,3); 2247 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2248 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2249 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2250 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2251 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->M,y->N); 2252 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2253 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n); 2254 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2255 2256 ierr = PetscLogEventBegin(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2257 if (mat->ops->solveadd) { 2258 ierr = (*mat->ops->solveadd)(mat,b,y,x);CHKERRQ(ierr); 2259 } else { 2260 /* do the solve then the add manually */ 2261 if (x != y) { 2262 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2263 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2264 } else { 2265 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2266 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2267 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2268 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 2269 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2270 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2271 } 2272 } 2273 ierr = PetscLogEventEnd(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 2274 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2275 PetscFunctionReturn(0); 2276 } 2277 2278 #undef __FUNCT__ 2279 #define __FUNCT__ "MatSolveTranspose" 2280 /*@ 2281 MatSolveTranspose - Solves A' x = b, given a factored matrix. 2282 2283 Collective on Mat and Vec 2284 2285 Input Parameters: 2286 + mat - the factored matrix 2287 - b - the right-hand-side vector 2288 2289 Output Parameter: 2290 . x - the result vector 2291 2292 Notes: 2293 The vectors b and x cannot be the same. I.e., one cannot 2294 call MatSolveTranspose(A,x,x). 2295 2296 Most users should employ the simplified KSP interface for linear solvers 2297 instead of working directly with matrix algebra routines such as this. 2298 See, e.g., KSPCreate(). 2299 2300 Level: developer 2301 2302 Concepts: matrices^triangular solves 2303 2304 .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd() 2305 @*/ 2306 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTranspose(Mat mat,Vec b,Vec x) 2307 { 2308 PetscErrorCode ierr; 2309 2310 PetscFunctionBegin; 2311 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2312 PetscValidType(mat,1); 2313 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2314 PetscValidHeaderSpecific(x,VEC_COOKIE,3); 2315 PetscCheckSameComm(mat,1,b,2); 2316 PetscCheckSameComm(mat,1,x,3); 2317 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2318 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2319 if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name); 2320 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 2321 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N); 2322 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2323 ierr = PetscLogEventBegin(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2324 ierr = (*mat->ops->solvetranspose)(mat,b,x);CHKERRQ(ierr); 2325 ierr = PetscLogEventEnd(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 2326 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2327 PetscFunctionReturn(0); 2328 } 2329 2330 #undef __FUNCT__ 2331 #define __FUNCT__ "MatSolveTransposeAdd" 2332 /*@ 2333 MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 2334 factored matrix. 2335 2336 Collective on Mat and Vec 2337 2338 Input Parameters: 2339 + mat - the factored matrix 2340 . b - the right-hand-side vector 2341 - y - the vector to be added to 2342 2343 Output Parameter: 2344 . x - the result vector 2345 2346 Notes: 2347 The vectors b and x cannot be the same. I.e., one cannot 2348 call MatSolveTransposeAdd(A,x,y,x). 2349 2350 Most users should employ the simplified KSP interface for linear solvers 2351 instead of working directly with matrix algebra routines such as this. 2352 See, e.g., KSPCreate(). 2353 2354 Level: developer 2355 2356 Concepts: matrices^triangular solves 2357 2358 .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose() 2359 @*/ 2360 PetscErrorCode PETSCMAT_DLLEXPORT MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x) 2361 { 2362 PetscScalar one = 1.0; 2363 PetscErrorCode ierr; 2364 Vec tmp; 2365 2366 PetscFunctionBegin; 2367 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2368 PetscValidType(mat,1); 2369 PetscValidHeaderSpecific(y,VEC_COOKIE,2); 2370 PetscValidHeaderSpecific(b,VEC_COOKIE,3); 2371 PetscValidHeaderSpecific(x,VEC_COOKIE,4); 2372 PetscCheckSameComm(mat,1,b,2); 2373 PetscCheckSameComm(mat,1,y,3); 2374 PetscCheckSameComm(mat,1,x,4); 2375 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 2376 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 2377 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->M,x->N); 2378 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->N,b->N); 2379 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %D %D",mat->N,y->N); 2380 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %D %D",x->n,y->n); 2381 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2382 2383 ierr = PetscLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2384 if (mat->ops->solvetransposeadd) { 2385 ierr = (*mat->ops->solvetransposeadd)(mat,b,y,x);CHKERRQ(ierr); 2386 } else { 2387 /* do the solve then the add manually */ 2388 if (x != y) { 2389 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2390 ierr = VecAXPY(x,one,y);CHKERRQ(ierr); 2391 } else { 2392 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 2393 ierr = PetscLogObjectParent(mat,tmp);CHKERRQ(ierr); 2394 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 2395 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 2396 ierr = VecAXPY(x,one,tmp);CHKERRQ(ierr); 2397 ierr = VecDestroy(tmp);CHKERRQ(ierr); 2398 } 2399 } 2400 ierr = PetscLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 2401 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2402 PetscFunctionReturn(0); 2403 } 2404 /* ----------------------------------------------------------------*/ 2405 2406 #undef __FUNCT__ 2407 #define __FUNCT__ "MatRelax" 2408 /*@ 2409 MatRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2410 2411 Collective on Mat and Vec 2412 2413 Input Parameters: 2414 + mat - the matrix 2415 . b - the right hand side 2416 . omega - the relaxation factor 2417 . flag - flag indicating the type of SOR (see below) 2418 . shift - diagonal shift 2419 - its - the number of iterations 2420 - lits - the number of local iterations 2421 2422 Output Parameters: 2423 . x - the solution (can contain an initial guess) 2424 2425 SOR Flags: 2426 . SOR_FORWARD_SWEEP - forward SOR 2427 . SOR_BACKWARD_SWEEP - backward SOR 2428 . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR) 2429 . SOR_LOCAL_FORWARD_SWEEP - local forward SOR 2430 . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 2431 . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR 2432 . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 2433 upper/lower triangular part of matrix to 2434 vector (with omega) 2435 . SOR_ZERO_INITIAL_GUESS - zero initial guess 2436 2437 Notes: 2438 SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and 2439 SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings 2440 on each processor. 2441 2442 Application programmers will not generally use MatRelax() directly, 2443 but instead will employ the KSP/PC interface. 2444 2445 Notes for Advanced Users: 2446 The flags are implemented as bitwise inclusive or operations. 2447 For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP) 2448 to specify a zero initial guess for SSOR. 2449 2450 Most users should employ the simplified KSP interface for linear solvers 2451 instead of working directly with matrix algebra routines such as this. 2452 See, e.g., KSPCreate(). 2453 2454 See also, MatPBRelax(). This routine will automatically call the point block 2455 version if the point version is not available. 2456 2457 Level: developer 2458 2459 Concepts: matrices^relaxation 2460 Concepts: matrices^SOR 2461 Concepts: matrices^Gauss-Seidel 2462 2463 @*/ 2464 PetscErrorCode PETSCMAT_DLLEXPORT MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2465 { 2466 PetscErrorCode ierr; 2467 2468 PetscFunctionBegin; 2469 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2470 PetscValidType(mat,1); 2471 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2472 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2473 PetscCheckSameComm(mat,1,b,2); 2474 PetscCheckSameComm(mat,1,x,8); 2475 if (!mat->ops->relax && !mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2476 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2477 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2478 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2479 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2480 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2481 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2482 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2483 if (mat->ops->relax) { 2484 ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2485 } else { 2486 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2487 } 2488 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2489 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2490 PetscFunctionReturn(0); 2491 } 2492 2493 #undef __FUNCT__ 2494 #define __FUNCT__ "MatPBRelax" 2495 /*@ 2496 MatPBRelax - Computes relaxation (SOR, Gauss-Seidel) sweeps. 2497 2498 Collective on Mat and Vec 2499 2500 See MatRelax() for usage 2501 2502 For multi-component PDEs where the Jacobian is stored in a point block format 2503 (with the PETSc BAIJ matrix formats) the relaxation is done one point block at 2504 a time. That is, the small (for example, 4 by 4) blocks along the diagonal are solved 2505 simultaneously (that is a 4 by 4 linear solve is done) to update all the values at a point. 2506 2507 Level: developer 2508 2509 @*/ 2510 PetscErrorCode PETSCMAT_DLLEXPORT MatPBRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,PetscInt its,PetscInt lits,Vec x) 2511 { 2512 PetscErrorCode ierr; 2513 2514 PetscFunctionBegin; 2515 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2516 PetscValidType(mat,1); 2517 PetscValidHeaderSpecific(b,VEC_COOKIE,2); 2518 PetscValidHeaderSpecific(x,VEC_COOKIE,8); 2519 PetscCheckSameComm(mat,1,b,2); 2520 PetscCheckSameComm(mat,1,x,8); 2521 if (!mat->ops->pbrelax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2522 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2523 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2524 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %D %D",mat->N,x->N); 2525 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %D %D",mat->M,b->N); 2526 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %D %D",mat->m,b->n); 2527 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2528 2529 ierr = PetscLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2530 ierr =(*mat->ops->pbrelax)(mat,b,omega,flag,shift,its,lits,x);CHKERRQ(ierr); 2531 ierr = PetscLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2532 ierr = PetscObjectStateIncrease((PetscObject)x);CHKERRQ(ierr); 2533 PetscFunctionReturn(0); 2534 } 2535 2536 #undef __FUNCT__ 2537 #define __FUNCT__ "MatCopy_Basic" 2538 /* 2539 Default matrix copy routine. 2540 */ 2541 PetscErrorCode MatCopy_Basic(Mat A,Mat B,MatStructure str) 2542 { 2543 PetscErrorCode ierr; 2544 PetscInt i,rstart,rend,nz; 2545 const PetscInt *cwork; 2546 const PetscScalar *vwork; 2547 2548 PetscFunctionBegin; 2549 if (B->assembled) { 2550 ierr = MatZeroEntries(B);CHKERRQ(ierr); 2551 } 2552 ierr = MatGetOwnershipRange(A,&rstart,&rend);CHKERRQ(ierr); 2553 for (i=rstart; i<rend; i++) { 2554 ierr = MatGetRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2555 ierr = MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);CHKERRQ(ierr); 2556 ierr = MatRestoreRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2557 } 2558 ierr = MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2559 ierr = MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2560 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2561 PetscFunctionReturn(0); 2562 } 2563 2564 #undef __FUNCT__ 2565 #define __FUNCT__ "MatCopy" 2566 /*@C 2567 MatCopy - Copys a matrix to another matrix. 2568 2569 Collective on Mat 2570 2571 Input Parameters: 2572 + A - the matrix 2573 - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN 2574 2575 Output Parameter: 2576 . B - where the copy is put 2577 2578 Notes: 2579 If you use SAME_NONZERO_PATTERN then the two matrices had better have the 2580 same nonzero pattern or the routine will crash. 2581 2582 MatCopy() copies the matrix entries of a matrix to another existing 2583 matrix (after first zeroing the second matrix). A related routine is 2584 MatConvert(), which first creates a new matrix and then copies the data. 2585 2586 Level: intermediate 2587 2588 Concepts: matrices^copying 2589 2590 .seealso: MatConvert(), MatDuplicate() 2591 2592 @*/ 2593 PetscErrorCode PETSCMAT_DLLEXPORT MatCopy(Mat A,Mat B,MatStructure str) 2594 { 2595 PetscErrorCode ierr; 2596 2597 PetscFunctionBegin; 2598 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 2599 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 2600 PetscValidType(A,1); 2601 PetscValidType(B,2); 2602 MatPreallocated(B); 2603 PetscCheckSameComm(A,1,B,2); 2604 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2605 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2606 if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim (%D,%D) (%D,%D)",A->M,B->M,A->N,B->N); 2607 ierr = MatPreallocated(A);CHKERRQ(ierr); 2608 2609 ierr = PetscLogEventBegin(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 2610 if (A->ops->copy) { 2611 ierr = (*A->ops->copy)(A,B,str);CHKERRQ(ierr); 2612 } else { /* generic conversion */ 2613 ierr = MatCopy_Basic(A,B,str);CHKERRQ(ierr); 2614 } 2615 if (A->mapping) { 2616 if (B->mapping) {ierr = ISLocalToGlobalMappingDestroy(B->mapping);CHKERRQ(ierr);B->mapping = 0;} 2617 ierr = MatSetLocalToGlobalMapping(B,A->mapping);CHKERRQ(ierr); 2618 } 2619 if (A->bmapping) { 2620 if (B->bmapping) {ierr = ISLocalToGlobalMappingDestroy(B->bmapping);CHKERRQ(ierr);B->bmapping = 0;} 2621 ierr = MatSetLocalToGlobalMappingBlock(B,A->mapping);CHKERRQ(ierr); 2622 } 2623 ierr = PetscLogEventEnd(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 2624 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2625 PetscFunctionReturn(0); 2626 } 2627 2628 #include "petscsys.h" 2629 PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE; 2630 PetscFList MatConvertList = 0; 2631 2632 #undef __FUNCT__ 2633 #define __FUNCT__ "MatConvertRegister" 2634 /*@C 2635 MatConvertRegister - Allows one to register a routine that converts a sparse matrix 2636 from one format to another. 2637 2638 Not Collective 2639 2640 Input Parameters: 2641 + type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ. 2642 - Converter - the function that reads the matrix from the binary file. 2643 2644 Level: developer 2645 2646 .seealso: MatConvertRegisterAll(), MatConvert() 2647 2648 @*/ 2649 PetscErrorCode PETSCMAT_DLLEXPORT MatConvertRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(Mat,MatType,MatReuse,Mat*)) 2650 { 2651 PetscErrorCode ierr; 2652 char fullname[PETSC_MAX_PATH_LEN]; 2653 2654 PetscFunctionBegin; 2655 ierr = PetscFListConcat(path,name,fullname);CHKERRQ(ierr); 2656 ierr = PetscFListAdd(&MatConvertList,sname,fullname,(void (*)(void))function);CHKERRQ(ierr); 2657 PetscFunctionReturn(0); 2658 } 2659 2660 #undef __FUNCT__ 2661 #define __FUNCT__ "MatConvert" 2662 /*@C 2663 MatConvert - Converts a matrix to another matrix, either of the same 2664 or different type. 2665 2666 Collective on Mat 2667 2668 Input Parameters: 2669 + mat - the matrix 2670 . newtype - new matrix type. Use MATSAME to create a new matrix of the 2671 same type as the original matrix. 2672 - reuse - denotes if the destination matrix is to be created or reused. Currently 2673 MAT_REUSE_MATRIX is only supported for inplace conversion, otherwise use 2674 MAT_INITIAL_MATRIX. 2675 Output Parameter: 2676 . M - pointer to place new matrix 2677 2678 Notes: 2679 MatConvert() first creates a new matrix and then copies the data from 2680 the first matrix. A related routine is MatCopy(), which copies the matrix 2681 entries of one matrix to another already existing matrix context. 2682 2683 Level: intermediate 2684 2685 Concepts: matrices^converting between storage formats 2686 2687 .seealso: MatCopy(), MatDuplicate() 2688 @*/ 2689 PetscErrorCode PETSCMAT_DLLEXPORT MatConvert(Mat mat,const MatType newtype,MatReuse reuse,Mat *M) 2690 { 2691 PetscErrorCode ierr; 2692 PetscTruth sametype,issame,flg; 2693 char convname[256],mtype[256]; 2694 Mat B; 2695 2696 PetscFunctionBegin; 2697 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2698 PetscValidType(mat,1); 2699 PetscValidPointer(M,3); 2700 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2701 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2702 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2703 2704 ierr = PetscOptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);CHKERRQ(ierr); 2705 if (flg) { 2706 newtype = mtype; 2707 } 2708 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2709 2710 ierr = PetscTypeCompare((PetscObject)mat,newtype,&sametype);CHKERRQ(ierr); 2711 ierr = PetscStrcmp(newtype,"same",&issame);CHKERRQ(ierr); 2712 if ((reuse==MAT_REUSE_MATRIX) && (mat != *M)) { 2713 SETERRQ(PETSC_ERR_SUP,"MAT_REUSE_MATRIX only supported for inplace convertion currently"); 2714 } 2715 if ((sametype || issame) && (reuse==MAT_INITIAL_MATRIX) && mat->ops->duplicate) { 2716 ierr = (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);CHKERRQ(ierr); 2717 } else { 2718 PetscErrorCode (*conv)(Mat,const MatType,MatReuse,Mat*)=PETSC_NULL; 2719 /* 2720 Order of precedence: 2721 1) See if a specialized converter is known to the current matrix. 2722 2) See if a specialized converter is known to the desired matrix class. 2723 3) See if a good general converter is registered for the desired class 2724 (as of 6/27/03 only MATMPIADJ falls into this category). 2725 4) See if a good general converter is known for the current matrix. 2726 5) Use a really basic converter. 2727 */ 2728 ierr = PetscStrcpy(convname,"MatConvert_");CHKERRQ(ierr); 2729 ierr = PetscStrcat(convname,mat->type_name);CHKERRQ(ierr); 2730 ierr = PetscStrcat(convname,"_");CHKERRQ(ierr); 2731 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 2732 ierr = PetscStrcat(convname,"_C");CHKERRQ(ierr); 2733 ierr = PetscObjectQueryFunction((PetscObject)mat,convname,(void (**)(void))&conv);CHKERRQ(ierr); 2734 2735 if (!conv) { 2736 ierr = MatCreate(mat->comm,0,0,0,0,&B);CHKERRQ(ierr); 2737 ierr = MatSetType(B,newtype);CHKERRQ(ierr); 2738 ierr = PetscObjectQueryFunction((PetscObject)B,convname,(void (**)(void))&conv);CHKERRQ(ierr); 2739 ierr = MatDestroy(B);CHKERRQ(ierr); 2740 if (!conv) { 2741 if (!MatConvertRegisterAllCalled) { 2742 ierr = MatConvertRegisterAll(PETSC_NULL);CHKERRQ(ierr); 2743 } 2744 ierr = PetscFListFind(mat->comm,MatConvertList,newtype,(void(**)(void))&conv);CHKERRQ(ierr); 2745 if (!conv) { 2746 if (mat->ops->convert) { 2747 conv = mat->ops->convert; 2748 } else { 2749 conv = MatConvert_Basic; 2750 } 2751 } 2752 } 2753 } 2754 ierr = (*conv)(mat,newtype,reuse,M);CHKERRQ(ierr); 2755 } 2756 B = *M; 2757 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2758 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2759 PetscFunctionReturn(0); 2760 } 2761 2762 2763 #undef __FUNCT__ 2764 #define __FUNCT__ "MatDuplicate" 2765 /*@C 2766 MatDuplicate - Duplicates a matrix including the non-zero structure. 2767 2768 Collective on Mat 2769 2770 Input Parameters: 2771 + mat - the matrix 2772 - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero 2773 values as well or not 2774 2775 Output Parameter: 2776 . M - pointer to place new matrix 2777 2778 Level: intermediate 2779 2780 Concepts: matrices^duplicating 2781 2782 .seealso: MatCopy(), MatConvert() 2783 @*/ 2784 PetscErrorCode PETSCMAT_DLLEXPORT MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M) 2785 { 2786 PetscErrorCode ierr; 2787 Mat B; 2788 2789 PetscFunctionBegin; 2790 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2791 PetscValidType(mat,1); 2792 PetscValidPointer(M,3); 2793 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2794 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2795 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2796 2797 *M = 0; 2798 ierr = PetscLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2799 if (!mat->ops->duplicate) { 2800 SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type"); 2801 } 2802 ierr = (*mat->ops->duplicate)(mat,op,M);CHKERRQ(ierr); 2803 B = *M; 2804 if (mat->mapping) { 2805 ierr = MatSetLocalToGlobalMapping(B,mat->mapping);CHKERRQ(ierr); 2806 } 2807 if (mat->bmapping) { 2808 ierr = MatSetLocalToGlobalMappingBlock(B,mat->bmapping);CHKERRQ(ierr); 2809 } 2810 if (mat->rmap){ 2811 if (!B->rmap){ 2812 ierr = PetscMapCreateMPI(B->comm,B->m,B->M,&B->rmap);CHKERRQ(ierr); 2813 } 2814 ierr = PetscMemcpy(B->rmap,mat->rmap,sizeof(PetscMap));CHKERRQ(ierr); 2815 } 2816 if (mat->cmap){ 2817 if (!B->cmap){ 2818 ierr = PetscMapCreateMPI(B->comm,B->n,B->N,&B->cmap);CHKERRQ(ierr); 2819 } 2820 ierr = PetscMemcpy(B->cmap,mat->cmap,sizeof(PetscMap));CHKERRQ(ierr); 2821 } 2822 ierr = PetscLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2823 ierr = PetscObjectStateIncrease((PetscObject)B);CHKERRQ(ierr); 2824 PetscFunctionReturn(0); 2825 } 2826 2827 #undef __FUNCT__ 2828 #define __FUNCT__ "MatGetDiagonal" 2829 /*@ 2830 MatGetDiagonal - Gets the diagonal of a matrix. 2831 2832 Collective on Mat and Vec 2833 2834 Input Parameters: 2835 + mat - the matrix 2836 - v - the vector for storing the diagonal 2837 2838 Output Parameter: 2839 . v - the diagonal of the matrix 2840 2841 Notes: 2842 For the SeqAIJ matrix format, this routine may also be called 2843 on a LU factored matrix; in that case it routines the reciprocal of 2844 the diagonal entries in U. It returns the entries permuted by the 2845 row and column permutation used during the symbolic factorization. 2846 2847 Level: intermediate 2848 2849 Concepts: matrices^accessing diagonals 2850 2851 .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax() 2852 @*/ 2853 PetscErrorCode PETSCMAT_DLLEXPORT MatGetDiagonal(Mat mat,Vec v) 2854 { 2855 PetscErrorCode ierr; 2856 2857 PetscFunctionBegin; 2858 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2859 PetscValidType(mat,1); 2860 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 2861 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2862 if (!mat->ops->getdiagonal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2863 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2864 2865 ierr = (*mat->ops->getdiagonal)(mat,v);CHKERRQ(ierr); 2866 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 2867 PetscFunctionReturn(0); 2868 } 2869 2870 #undef __FUNCT__ 2871 #define __FUNCT__ "MatGetRowMax" 2872 /*@ 2873 MatGetRowMax - Gets the maximum value (in absolute value) of each 2874 row of the matrix 2875 2876 Collective on Mat and Vec 2877 2878 Input Parameters: 2879 . mat - the matrix 2880 2881 Output Parameter: 2882 . v - the vector for storing the maximums 2883 2884 Level: intermediate 2885 2886 Concepts: matrices^getting row maximums 2887 2888 .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix() 2889 @*/ 2890 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowMax(Mat mat,Vec v) 2891 { 2892 PetscErrorCode ierr; 2893 2894 PetscFunctionBegin; 2895 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2896 PetscValidType(mat,1); 2897 PetscValidHeaderSpecific(v,VEC_COOKIE,2); 2898 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2899 if (!mat->ops->getrowmax) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2900 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2901 2902 ierr = (*mat->ops->getrowmax)(mat,v);CHKERRQ(ierr); 2903 ierr = PetscObjectStateIncrease((PetscObject)v);CHKERRQ(ierr); 2904 PetscFunctionReturn(0); 2905 } 2906 2907 #undef __FUNCT__ 2908 #define __FUNCT__ "MatTranspose" 2909 /*@C 2910 MatTranspose - Computes an in-place or out-of-place transpose of a matrix. 2911 2912 Collective on Mat 2913 2914 Input Parameter: 2915 . mat - the matrix to transpose 2916 2917 Output Parameters: 2918 . B - the transpose (or pass in PETSC_NULL for an in-place transpose) 2919 2920 Level: intermediate 2921 2922 Concepts: matrices^transposing 2923 2924 .seealso: MatMultTranspose(), MatMultTransposeAdd(), MatIsTranspose() 2925 @*/ 2926 PetscErrorCode PETSCMAT_DLLEXPORT MatTranspose(Mat mat,Mat *B) 2927 { 2928 PetscErrorCode ierr; 2929 2930 PetscFunctionBegin; 2931 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 2932 PetscValidType(mat,1); 2933 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2934 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2935 if (!mat->ops->transpose) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 2936 ierr = MatPreallocated(mat);CHKERRQ(ierr); 2937 2938 ierr = PetscLogEventBegin(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 2939 ierr = (*mat->ops->transpose)(mat,B);CHKERRQ(ierr); 2940 ierr = PetscLogEventEnd(MAT_Transpose,mat,0,0,0);CHKERRQ(ierr); 2941 if (B) {ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr);} 2942 PetscFunctionReturn(0); 2943 } 2944 2945 #undef __FUNCT__ 2946 #define __FUNCT__ "MatIsTranspose" 2947 /*@C 2948 MatIsTranspose - Test whether a matrix is another one's transpose, 2949 or its own, in which case it tests symmetry. 2950 2951 Collective on Mat 2952 2953 Input Parameter: 2954 + A - the matrix to test 2955 - B - the matrix to test against, this can equal the first parameter 2956 2957 Output Parameters: 2958 . flg - the result 2959 2960 Notes: 2961 Only available for SeqAIJ/MPIAIJ matrices. The sequential algorithm 2962 has a running time of the order of the number of nonzeros; the parallel 2963 test involves parallel copies of the block-offdiagonal parts of the matrix. 2964 2965 Level: intermediate 2966 2967 Concepts: matrices^transposing, matrix^symmetry 2968 2969 .seealso: MatTranspose(), MatIsSymmetric(), MatIsHermitian() 2970 @*/ 2971 PetscErrorCode PETSCMAT_DLLEXPORT MatIsTranspose(Mat A,Mat B,PetscReal tol,PetscTruth *flg) 2972 { 2973 PetscErrorCode ierr,(*f)(Mat,Mat,PetscReal,PetscTruth*),(*g)(Mat,Mat,PetscReal,PetscTruth*); 2974 2975 PetscFunctionBegin; 2976 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 2977 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 2978 PetscValidPointer(flg,3); 2979 ierr = PetscObjectQueryFunction((PetscObject)A,"MatIsTranspose_C",(void (**)(void))&f);CHKERRQ(ierr); 2980 ierr = PetscObjectQueryFunction((PetscObject)B,"MatIsTranspose_C",(void (**)(void))&g);CHKERRQ(ierr); 2981 if (f && g) { 2982 if (f==g) { 2983 ierr = (*f)(A,B,tol,flg);CHKERRQ(ierr); 2984 } else { 2985 SETERRQ(PETSC_ERR_ARG_NOTSAMETYPE,"Matrices do not have the same comparator for symmetry test"); 2986 } 2987 } 2988 PetscFunctionReturn(0); 2989 } 2990 2991 #undef __FUNCT__ 2992 #define __FUNCT__ "MatPermute" 2993 /*@C 2994 MatPermute - Creates a new matrix with rows and columns permuted from the 2995 original. 2996 2997 Collective on Mat 2998 2999 Input Parameters: 3000 + mat - the matrix to permute 3001 . row - row permutation, each processor supplies only the permutation for its rows 3002 - col - column permutation, each processor needs the entire column permutation, that is 3003 this is the same size as the total number of columns in the matrix 3004 3005 Output Parameters: 3006 . B - the permuted matrix 3007 3008 Level: advanced 3009 3010 Concepts: matrices^permuting 3011 3012 .seealso: MatGetOrdering() 3013 @*/ 3014 PetscErrorCode PETSCMAT_DLLEXPORT MatPermute(Mat mat,IS row,IS col,Mat *B) 3015 { 3016 PetscErrorCode ierr; 3017 3018 PetscFunctionBegin; 3019 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3020 PetscValidType(mat,1); 3021 PetscValidHeaderSpecific(row,IS_COOKIE,2); 3022 PetscValidHeaderSpecific(col,IS_COOKIE,3); 3023 PetscValidPointer(B,4); 3024 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3025 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3026 if (!mat->ops->permute) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3027 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3028 3029 ierr = (*mat->ops->permute)(mat,row,col,B);CHKERRQ(ierr); 3030 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3031 PetscFunctionReturn(0); 3032 } 3033 3034 #undef __FUNCT__ 3035 #define __FUNCT__ "MatPermuteSparsify" 3036 /*@C 3037 MatPermuteSparsify - Creates a new matrix with rows and columns permuted from the 3038 original and sparsified to the prescribed tolerance. 3039 3040 Collective on Mat 3041 3042 Input Parameters: 3043 + A - The matrix to permute 3044 . band - The half-bandwidth of the sparsified matrix, or PETSC_DECIDE 3045 . frac - The half-bandwidth as a fraction of the total size, or 0.0 3046 . tol - The drop tolerance 3047 . rowp - The row permutation 3048 - colp - The column permutation 3049 3050 Output Parameter: 3051 . B - The permuted, sparsified matrix 3052 3053 Level: advanced 3054 3055 Note: 3056 The default behavior (band = PETSC_DECIDE and frac = 0.0) is to 3057 restrict the half-bandwidth of the resulting matrix to 5% of the 3058 total matrix size. 3059 3060 .keywords: matrix, permute, sparsify 3061 3062 .seealso: MatGetOrdering(), MatPermute() 3063 @*/ 3064 PetscErrorCode PETSCMAT_DLLEXPORT MatPermuteSparsify(Mat A, PetscInt band, PetscReal frac, PetscReal tol, IS rowp, IS colp, Mat *B) 3065 { 3066 IS irowp, icolp; 3067 PetscInt *rows, *cols; 3068 PetscInt M, N, locRowStart, locRowEnd; 3069 PetscInt nz, newNz; 3070 const PetscInt *cwork; 3071 PetscInt *cnew; 3072 const PetscScalar *vwork; 3073 PetscScalar *vnew; 3074 PetscInt bw, issize; 3075 PetscInt row, locRow, newRow, col, newCol; 3076 PetscErrorCode ierr; 3077 3078 PetscFunctionBegin; 3079 PetscValidHeaderSpecific(A, MAT_COOKIE,1); 3080 PetscValidHeaderSpecific(rowp, IS_COOKIE,5); 3081 PetscValidHeaderSpecific(colp, IS_COOKIE,6); 3082 PetscValidPointer(B,7); 3083 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix"); 3084 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for factored matrix"); 3085 if (!A->ops->permutesparsify) { 3086 ierr = MatGetSize(A, &M, &N);CHKERRQ(ierr); 3087 ierr = MatGetOwnershipRange(A, &locRowStart, &locRowEnd);CHKERRQ(ierr); 3088 ierr = ISGetSize(rowp, &issize);CHKERRQ(ierr); 3089 if (issize != M) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for row permutation, should be %D", issize, M); 3090 ierr = ISGetSize(colp, &issize);CHKERRQ(ierr); 3091 if (issize != N) SETERRQ2(PETSC_ERR_ARG_WRONG, "Wrong size %D for column permutation, should be %D", issize, N); 3092 ierr = ISInvertPermutation(rowp, 0, &irowp);CHKERRQ(ierr); 3093 ierr = ISGetIndices(irowp, &rows);CHKERRQ(ierr); 3094 ierr = ISInvertPermutation(colp, 0, &icolp);CHKERRQ(ierr); 3095 ierr = ISGetIndices(icolp, &cols);CHKERRQ(ierr); 3096 ierr = PetscMalloc(N * sizeof(PetscInt), &cnew);CHKERRQ(ierr); 3097 ierr = PetscMalloc(N * sizeof(PetscScalar), &vnew);CHKERRQ(ierr); 3098 3099 /* Setup bandwidth to include */ 3100 if (band == PETSC_DECIDE) { 3101 if (frac <= 0.0) 3102 bw = (PetscInt) (M * 0.05); 3103 else 3104 bw = (PetscInt) (M * frac); 3105 } else { 3106 if (band <= 0) SETERRQ(PETSC_ERR_ARG_WRONG, "Bandwidth must be a positive integer"); 3107 bw = band; 3108 } 3109 3110 /* Put values into new matrix */ 3111 ierr = MatDuplicate(A, MAT_DO_NOT_COPY_VALUES, B);CHKERRQ(ierr); 3112 for(row = locRowStart, locRow = 0; row < locRowEnd; row++, locRow++) { 3113 ierr = MatGetRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3114 newRow = rows[locRow]+locRowStart; 3115 for(col = 0, newNz = 0; col < nz; col++) { 3116 newCol = cols[cwork[col]]; 3117 if ((newCol >= newRow - bw) && (newCol < newRow + bw) && (PetscAbsScalar(vwork[col]) >= tol)) { 3118 cnew[newNz] = newCol; 3119 vnew[newNz] = vwork[col]; 3120 newNz++; 3121 } 3122 } 3123 ierr = MatSetValues(*B, 1, &newRow, newNz, cnew, vnew, INSERT_VALUES);CHKERRQ(ierr); 3124 ierr = MatRestoreRow(A, row, &nz, &cwork, &vwork);CHKERRQ(ierr); 3125 } 3126 ierr = PetscFree(cnew);CHKERRQ(ierr); 3127 ierr = PetscFree(vnew);CHKERRQ(ierr); 3128 ierr = MatAssemblyBegin(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3129 ierr = MatAssemblyEnd(*B, MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 3130 ierr = ISRestoreIndices(irowp, &rows);CHKERRQ(ierr); 3131 ierr = ISRestoreIndices(icolp, &cols);CHKERRQ(ierr); 3132 ierr = ISDestroy(irowp);CHKERRQ(ierr); 3133 ierr = ISDestroy(icolp);CHKERRQ(ierr); 3134 } else { 3135 ierr = (*A->ops->permutesparsify)(A, band, frac, tol, rowp, colp, B);CHKERRQ(ierr); 3136 } 3137 ierr = PetscObjectStateIncrease((PetscObject)*B);CHKERRQ(ierr); 3138 PetscFunctionReturn(0); 3139 } 3140 3141 #undef __FUNCT__ 3142 #define __FUNCT__ "MatEqual" 3143 /*@ 3144 MatEqual - Compares two matrices. 3145 3146 Collective on Mat 3147 3148 Input Parameters: 3149 + A - the first matrix 3150 - B - the second matrix 3151 3152 Output Parameter: 3153 . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise. 3154 3155 Level: intermediate 3156 3157 Concepts: matrices^equality between 3158 @*/ 3159 PetscErrorCode PETSCMAT_DLLEXPORT MatEqual(Mat A,Mat B,PetscTruth *flg) 3160 { 3161 PetscErrorCode ierr; 3162 3163 PetscFunctionBegin; 3164 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 3165 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 3166 PetscValidType(A,1); 3167 PetscValidType(B,2); 3168 MatPreallocated(B); 3169 PetscValidIntPointer(flg,3); 3170 PetscCheckSameComm(A,1,B,2); 3171 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3172 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3173 if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %D %D %D %D",A->M,B->M,A->N,B->N); 3174 if (!A->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",A->type_name); 3175 if (!B->ops->equal) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",B->type_name); 3176 if (A->ops->equal != B->ops->equal) SETERRQ2(PETSC_ERR_ARG_INCOMP,"A is type: %s\nB is type: %s",A->type_name,B->type_name); 3177 ierr = MatPreallocated(A);CHKERRQ(ierr); 3178 3179 ierr = (*A->ops->equal)(A,B,flg);CHKERRQ(ierr); 3180 PetscFunctionReturn(0); 3181 } 3182 3183 #undef __FUNCT__ 3184 #define __FUNCT__ "MatDiagonalScale" 3185 /*@ 3186 MatDiagonalScale - Scales a matrix on the left and right by diagonal 3187 matrices that are stored as vectors. Either of the two scaling 3188 matrices can be PETSC_NULL. 3189 3190 Collective on Mat 3191 3192 Input Parameters: 3193 + mat - the matrix to be scaled 3194 . l - the left scaling vector (or PETSC_NULL) 3195 - r - the right scaling vector (or PETSC_NULL) 3196 3197 Notes: 3198 MatDiagonalScale() computes A = LAR, where 3199 L = a diagonal matrix (stored as a vector), R = a diagonal matrix (stored as a vector) 3200 3201 Level: intermediate 3202 3203 Concepts: matrices^diagonal scaling 3204 Concepts: diagonal scaling of matrices 3205 3206 .seealso: MatScale() 3207 @*/ 3208 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r) 3209 { 3210 PetscErrorCode ierr; 3211 3212 PetscFunctionBegin; 3213 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3214 PetscValidType(mat,1); 3215 if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3216 if (l) {PetscValidHeaderSpecific(l,VEC_COOKIE,2);PetscCheckSameComm(mat,1,l,2);} 3217 if (r) {PetscValidHeaderSpecific(r,VEC_COOKIE,3);PetscCheckSameComm(mat,1,r,3);} 3218 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3219 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3220 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3221 3222 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3223 ierr = (*mat->ops->diagonalscale)(mat,l,r);CHKERRQ(ierr); 3224 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3225 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3226 PetscFunctionReturn(0); 3227 } 3228 3229 #undef __FUNCT__ 3230 #define __FUNCT__ "MatScale" 3231 /*@ 3232 MatScale - Scales all elements of a matrix by a given number. 3233 3234 Collective on Mat 3235 3236 Input Parameters: 3237 + mat - the matrix to be scaled 3238 - a - the scaling value 3239 3240 Output Parameter: 3241 . mat - the scaled matrix 3242 3243 Level: intermediate 3244 3245 Concepts: matrices^scaling all entries 3246 3247 .seealso: MatDiagonalScale() 3248 @*/ 3249 PetscErrorCode PETSCMAT_DLLEXPORT MatScale(const PetscScalar *a,Mat mat) 3250 { 3251 PetscErrorCode ierr; 3252 3253 PetscFunctionBegin; 3254 PetscValidScalarPointer(a,1); 3255 PetscValidHeaderSpecific(mat,MAT_COOKIE,2); 3256 PetscValidType(mat,2); 3257 if (!mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3258 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3259 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3260 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3261 3262 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3263 ierr = (*mat->ops->scale)(a,mat);CHKERRQ(ierr); 3264 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 3265 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3266 PetscFunctionReturn(0); 3267 } 3268 3269 #undef __FUNCT__ 3270 #define __FUNCT__ "MatNorm" 3271 /*@ 3272 MatNorm - Calculates various norms of a matrix. 3273 3274 Collective on Mat 3275 3276 Input Parameters: 3277 + mat - the matrix 3278 - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY 3279 3280 Output Parameters: 3281 . nrm - the resulting norm 3282 3283 Level: intermediate 3284 3285 Concepts: matrices^norm 3286 Concepts: norm^of matrix 3287 @*/ 3288 PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm) 3289 { 3290 PetscErrorCode ierr; 3291 3292 PetscFunctionBegin; 3293 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3294 PetscValidType(mat,1); 3295 PetscValidScalarPointer(nrm,3); 3296 3297 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3298 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3299 if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3300 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3301 3302 ierr = (*mat->ops->norm)(mat,type,nrm);CHKERRQ(ierr); 3303 PetscFunctionReturn(0); 3304 } 3305 3306 /* 3307 This variable is used to prevent counting of MatAssemblyBegin() that 3308 are called from within a MatAssemblyEnd(). 3309 */ 3310 static PetscInt MatAssemblyEnd_InUse = 0; 3311 #undef __FUNCT__ 3312 #define __FUNCT__ "MatAssemblyBegin" 3313 /*@ 3314 MatAssemblyBegin - Begins assembling the matrix. This routine should 3315 be called after completing all calls to MatSetValues(). 3316 3317 Collective on Mat 3318 3319 Input Parameters: 3320 + mat - the matrix 3321 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3322 3323 Notes: 3324 MatSetValues() generally caches the values. The matrix is ready to 3325 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3326 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3327 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3328 using the matrix. 3329 3330 Level: beginner 3331 3332 Concepts: matrices^assembling 3333 3334 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled() 3335 @*/ 3336 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type) 3337 { 3338 PetscErrorCode ierr; 3339 3340 PetscFunctionBegin; 3341 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3342 PetscValidType(mat,1); 3343 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3344 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?"); 3345 if (mat->assembled) { 3346 mat->was_assembled = PETSC_TRUE; 3347 mat->assembled = PETSC_FALSE; 3348 } 3349 if (!MatAssemblyEnd_InUse) { 3350 ierr = PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3351 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3352 ierr = PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 3353 } else { 3354 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 3355 } 3356 PetscFunctionReturn(0); 3357 } 3358 3359 #undef __FUNCT__ 3360 #define __FUNCT__ "MatAssembed" 3361 /*@ 3362 MatAssembled - Indicates if a matrix has been assembled and is ready for 3363 use; for example, in matrix-vector product. 3364 3365 Collective on Mat 3366 3367 Input Parameter: 3368 . mat - the matrix 3369 3370 Output Parameter: 3371 . assembled - PETSC_TRUE or PETSC_FALSE 3372 3373 Level: advanced 3374 3375 Concepts: matrices^assembled? 3376 3377 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin() 3378 @*/ 3379 PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled) 3380 { 3381 PetscFunctionBegin; 3382 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3383 PetscValidType(mat,1); 3384 PetscValidPointer(assembled,2); 3385 *assembled = mat->assembled; 3386 PetscFunctionReturn(0); 3387 } 3388 3389 #undef __FUNCT__ 3390 #define __FUNCT__ "MatView_Private" 3391 /* 3392 Processes command line options to determine if/how a matrix 3393 is to be viewed. Called by MatAssemblyEnd() and MatLoad(). 3394 */ 3395 PetscErrorCode MatView_Private(Mat mat) 3396 { 3397 PetscErrorCode ierr; 3398 PetscTruth flg; 3399 static PetscTruth incall = PETSC_FALSE; 3400 3401 PetscFunctionBegin; 3402 if (incall) PetscFunctionReturn(0); 3403 incall = PETSC_TRUE; 3404 ierr = PetscOptionsBegin(mat->comm,mat->prefix,"Matrix Options","Mat");CHKERRQ(ierr); 3405 ierr = PetscOptionsName("-mat_view_info","Information on matrix size","MatView",&flg);CHKERRQ(ierr); 3406 if (flg) { 3407 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO);CHKERRQ(ierr); 3408 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3409 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3410 } 3411 ierr = PetscOptionsName("-mat_view_info_detailed","Nonzeros in the matrix","MatView",&flg);CHKERRQ(ierr); 3412 if (flg) { 3413 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_INFO_DETAIL);CHKERRQ(ierr); 3414 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3415 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3416 } 3417 ierr = PetscOptionsName("-mat_view","Print matrix to stdout","MatView",&flg);CHKERRQ(ierr); 3418 if (flg) { 3419 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3420 } 3421 ierr = PetscOptionsName("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",&flg);CHKERRQ(ierr); 3422 if (flg) { 3423 ierr = PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(mat->comm),PETSC_VIEWER_ASCII_MATLAB);CHKERRQ(ierr); 3424 ierr = MatView(mat,PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3425 ierr = PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 3426 } 3427 #if defined(PETSC_USE_SOCKET_VIEWER) 3428 ierr = PetscOptionsName("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",&flg);CHKERRQ(ierr); 3429 if (flg) { 3430 ierr = MatView(mat,PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3431 ierr = PetscViewerFlush(PETSC_VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 3432 } 3433 #endif 3434 ierr = PetscOptionsName("-mat_view_binary","Save matrix to file in binary format","MatView",&flg);CHKERRQ(ierr); 3435 if (flg) { 3436 ierr = MatView(mat,PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3437 ierr = PetscViewerFlush(PETSC_VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 3438 } 3439 ierr = PetscOptionsEnd();CHKERRQ(ierr); 3440 /* cannot have inside PetscOptionsBegin() because uses PetscOptionsBegin() */ 3441 ierr = PetscOptionsHasName(mat->prefix,"-mat_view_draw",&flg);CHKERRQ(ierr); 3442 if (flg) { 3443 ierr = PetscOptionsHasName(mat->prefix,"-mat_view_contour",&flg);CHKERRQ(ierr); 3444 if (flg) { 3445 PetscViewerPushFormat(PETSC_VIEWER_DRAW_(mat->comm),PETSC_VIEWER_DRAW_CONTOUR);CHKERRQ(ierr); 3446 } 3447 ierr = MatView(mat,PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3448 ierr = PetscViewerFlush(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3449 if (flg) { 3450 PetscViewerPopFormat(PETSC_VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 3451 } 3452 } 3453 incall = PETSC_FALSE; 3454 PetscFunctionReturn(0); 3455 } 3456 3457 #undef __FUNCT__ 3458 #define __FUNCT__ "MatAssemblyEnd" 3459 /*@ 3460 MatAssemblyEnd - Completes assembling the matrix. This routine should 3461 be called after MatAssemblyBegin(). 3462 3463 Collective on Mat 3464 3465 Input Parameters: 3466 + mat - the matrix 3467 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 3468 3469 Options Database Keys: 3470 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 3471 . -mat_view_info_detailed - Prints more detailed info 3472 . -mat_view - Prints matrix in ASCII format 3473 . -mat_view_matlab - Prints matrix in Matlab format 3474 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 3475 . -display <name> - Sets display name (default is host) 3476 . -draw_pause <sec> - Sets number of seconds to pause after display 3477 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 3478 . -viewer_socket_machine <machine> 3479 . -viewer_socket_port <port> 3480 . -mat_view_binary - save matrix to file in binary format 3481 - -viewer_binary_filename <name> 3482 3483 Notes: 3484 MatSetValues() generally caches the values. The matrix is ready to 3485 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 3486 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 3487 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 3488 using the matrix. 3489 3490 Level: beginner 3491 3492 .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen() 3493 @*/ 3494 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type) 3495 { 3496 PetscErrorCode ierr; 3497 static PetscInt inassm = 0; 3498 PetscTruth flg; 3499 3500 PetscFunctionBegin; 3501 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3502 PetscValidType(mat,1); 3503 3504 inassm++; 3505 MatAssemblyEnd_InUse++; 3506 if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */ 3507 ierr = PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3508 if (mat->ops->assemblyend) { 3509 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3510 } 3511 ierr = PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 3512 } else { 3513 if (mat->ops->assemblyend) { 3514 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 3515 } 3516 } 3517 3518 /* Flush assembly is not a true assembly */ 3519 if (type != MAT_FLUSH_ASSEMBLY) { 3520 mat->assembled = PETSC_TRUE; mat->num_ass++; 3521 } 3522 mat->insertmode = NOT_SET_VALUES; 3523 MatAssemblyEnd_InUse--; 3524 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3525 if (!mat->symmetric_eternal) { 3526 mat->symmetric_set = PETSC_FALSE; 3527 mat->hermitian_set = PETSC_FALSE; 3528 mat->structurally_symmetric_set = PETSC_FALSE; 3529 } 3530 if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) { 3531 ierr = MatView_Private(mat);CHKERRQ(ierr); 3532 ierr = PetscOptionsHasName(mat->prefix,"-mat_is_symmetric",&flg);CHKERRQ(ierr); 3533 if (flg) { 3534 PetscReal tol = 0.0; 3535 ierr = PetscOptionsGetReal(mat->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);CHKERRQ(ierr); 3536 ierr = MatIsSymmetric(mat,tol,&flg);CHKERRQ(ierr); 3537 if (flg) { 3538 ierr = PetscPrintf(mat->comm,"Matrix is symmetric (tolerance %g)\n",tol);CHKERRQ(ierr); 3539 } else { 3540 ierr = PetscPrintf(mat->comm,"Matrix is not symmetric (tolerance %g)\n",tol);CHKERRQ(ierr); 3541 } 3542 } 3543 } 3544 inassm--; 3545 ierr = PetscOptionsHasName(mat->prefix,"-help",&flg);CHKERRQ(ierr); 3546 if (flg) { 3547 ierr = MatPrintHelp(mat);CHKERRQ(ierr); 3548 } 3549 PetscFunctionReturn(0); 3550 } 3551 3552 3553 #undef __FUNCT__ 3554 #define __FUNCT__ "MatCompress" 3555 /*@ 3556 MatCompress - Tries to store the matrix in as little space as 3557 possible. May fail if memory is already fully used, since it 3558 tries to allocate new space. 3559 3560 Collective on Mat 3561 3562 Input Parameters: 3563 . mat - the matrix 3564 3565 Level: advanced 3566 3567 @*/ 3568 PetscErrorCode PETSCMAT_DLLEXPORT MatCompress(Mat mat) 3569 { 3570 PetscErrorCode ierr; 3571 3572 PetscFunctionBegin; 3573 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3574 PetscValidType(mat,1); 3575 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3576 if (mat->ops->compress) {ierr = (*mat->ops->compress)(mat);CHKERRQ(ierr);} 3577 PetscFunctionReturn(0); 3578 } 3579 3580 #undef __FUNCT__ 3581 #define __FUNCT__ "MatSetOption" 3582 /*@ 3583 MatSetOption - Sets a parameter option for a matrix. Some options 3584 may be specific to certain storage formats. Some options 3585 determine how values will be inserted (or added). Sorted, 3586 row-oriented input will generally assemble the fastest. The default 3587 is row-oriented, nonsorted input. 3588 3589 Collective on Mat 3590 3591 Input Parameters: 3592 + mat - the matrix 3593 - option - the option, one of those listed below (and possibly others), 3594 e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR 3595 3596 Options Describing Matrix Structure: 3597 + MAT_SYMMETRIC - symmetric in terms of both structure and value 3598 . MAT_HERMITIAN - transpose is the complex conjugation 3599 . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 3600 . MAT_NOT_SYMMETRIC - not symmetric in value 3601 . MAT_NOT_HERMITIAN - transpose is not the complex conjugation 3602 . MAT_NOT_STRUCTURALLY_SYMMETRIC - not symmetric nonzero structure 3603 . MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag 3604 you set to be kept with all future use of the matrix 3605 including after MatAssemblyBegin/End() which could 3606 potentially change the symmetry structure, i.e. you 3607 KNOW the matrix will ALWAYS have the property you set. 3608 - MAT_NOT_SYMMETRY_ETERNAL - if MatAssemblyBegin/End() is called then the 3609 flags you set will be dropped (in case potentially 3610 the symmetry etc was lost). 3611 3612 Options For Use with MatSetValues(): 3613 Insert a logically dense subblock, which can be 3614 + MAT_ROW_ORIENTED - row-oriented (default) 3615 . MAT_COLUMN_ORIENTED - column-oriented 3616 . MAT_ROWS_SORTED - sorted by row 3617 . MAT_ROWS_UNSORTED - not sorted by row (default) 3618 . MAT_COLUMNS_SORTED - sorted by column 3619 - MAT_COLUMNS_UNSORTED - not sorted by column (default) 3620 3621 Not these options reflect the data you pass in with MatSetValues(); it has 3622 nothing to do with how the data is stored internally in the matrix 3623 data structure. 3624 3625 When (re)assembling a matrix, we can restrict the input for 3626 efficiency/debugging purposes. These options include 3627 + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be 3628 allowed if they generate a new nonzero 3629 . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed 3630 . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if 3631 they generate a nonzero in a new diagonal (for block diagonal format only) 3632 . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 3633 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 3634 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 3635 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 3636 3637 Notes: 3638 Some options are relevant only for particular matrix types and 3639 are thus ignored by others. Other options are not supported by 3640 certain matrix types and will generate an error message if set. 3641 3642 If using a Fortran 77 module to compute a matrix, one may need to 3643 use the column-oriented option (or convert to the row-oriented 3644 format). 3645 3646 MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 3647 that would generate a new entry in the nonzero structure is instead 3648 ignored. Thus, if memory has not alredy been allocated for this particular 3649 data, then the insertion is ignored. For dense matrices, in which 3650 the entire array is allocated, no entries are ever ignored. 3651 Set after the first MatAssemblyEnd() 3652 3653 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 3654 that would generate a new entry in the nonzero structure instead produces 3655 an error. (Currently supported for AIJ and BAIJ formats only.) 3656 This is a useful flag when using SAME_NONZERO_PATTERN in calling 3657 KSPSetOperators() to ensure that the nonzero pattern truely does 3658 remain unchanged. Set after the first MatAssemblyEnd() 3659 3660 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 3661 that would generate a new entry that has not been preallocated will 3662 instead produce an error. (Currently supported for AIJ and BAIJ formats 3663 only.) This is a useful flag when debugging matrix memory preallocation. 3664 3665 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 3666 other processors should be dropped, rather than stashed. 3667 This is useful if you know that the "owning" processor is also 3668 always generating the correct matrix entries, so that PETSc need 3669 not transfer duplicate entries generated on another processor. 3670 3671 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 3672 searches during matrix assembly. When this flag is set, the hash table 3673 is created during the first Matrix Assembly. This hash table is 3674 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 3675 to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 3676 should be used with MAT_USE_HASH_TABLE flag. This option is currently 3677 supported by MATMPIBAIJ format only. 3678 3679 MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries 3680 are kept in the nonzero structure 3681 3682 MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating 3683 a zero location in the matrix 3684 3685 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 3686 ROWBS matrix types 3687 3688 MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works 3689 with AIJ and ROWBS matrix types 3690 3691 Level: intermediate 3692 3693 Concepts: matrices^setting options 3694 3695 @*/ 3696 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op) 3697 { 3698 PetscErrorCode ierr; 3699 3700 PetscFunctionBegin; 3701 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3702 PetscValidType(mat,1); 3703 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3704 switch (op) { 3705 case MAT_SYMMETRIC: 3706 mat->symmetric = PETSC_TRUE; 3707 mat->structurally_symmetric = PETSC_TRUE; 3708 mat->symmetric_set = PETSC_TRUE; 3709 mat->structurally_symmetric_set = PETSC_TRUE; 3710 break; 3711 case MAT_HERMITIAN: 3712 mat->hermitian = PETSC_TRUE; 3713 mat->structurally_symmetric = PETSC_TRUE; 3714 mat->hermitian_set = PETSC_TRUE; 3715 mat->structurally_symmetric_set = PETSC_TRUE; 3716 break; 3717 case MAT_STRUCTURALLY_SYMMETRIC: 3718 mat->structurally_symmetric = PETSC_TRUE; 3719 mat->structurally_symmetric_set = PETSC_TRUE; 3720 break; 3721 case MAT_NOT_SYMMETRIC: 3722 mat->symmetric = PETSC_FALSE; 3723 mat->symmetric_set = PETSC_TRUE; 3724 break; 3725 case MAT_NOT_HERMITIAN: 3726 mat->hermitian = PETSC_FALSE; 3727 mat->hermitian_set = PETSC_TRUE; 3728 break; 3729 case MAT_NOT_STRUCTURALLY_SYMMETRIC: 3730 mat->structurally_symmetric = PETSC_FALSE; 3731 mat->structurally_symmetric_set = PETSC_TRUE; 3732 break; 3733 case MAT_SYMMETRY_ETERNAL: 3734 mat->symmetric_eternal = PETSC_TRUE; 3735 break; 3736 case MAT_NOT_SYMMETRY_ETERNAL: 3737 mat->symmetric_eternal = PETSC_FALSE; 3738 break; 3739 default: 3740 break; 3741 } 3742 if (mat->ops->setoption) { 3743 ierr = (*mat->ops->setoption)(mat,op);CHKERRQ(ierr); 3744 } 3745 PetscFunctionReturn(0); 3746 } 3747 3748 #undef __FUNCT__ 3749 #define __FUNCT__ "MatZeroEntries" 3750 /*@ 3751 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 3752 this routine retains the old nonzero structure. 3753 3754 Collective on Mat 3755 3756 Input Parameters: 3757 . mat - the matrix 3758 3759 Level: intermediate 3760 3761 Concepts: matrices^zeroing 3762 3763 .seealso: MatZeroRows() 3764 @*/ 3765 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat) 3766 { 3767 PetscErrorCode ierr; 3768 3769 PetscFunctionBegin; 3770 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3771 PetscValidType(mat,1); 3772 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3773 if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled"); 3774 if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3775 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3776 3777 ierr = PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 3778 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 3779 ierr = PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 3780 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3781 PetscFunctionReturn(0); 3782 } 3783 3784 #undef __FUNCT__ 3785 #define __FUNCT__ "MatZeroRows" 3786 /*@C 3787 MatZeroRows - Zeros all entries (except possibly the main diagonal) 3788 of a set of rows of a matrix. 3789 3790 Collective on Mat 3791 3792 Input Parameters: 3793 + mat - the matrix 3794 . is - index set of rows to remove 3795 - diag - pointer to value put in all diagonals of eliminated rows. 3796 Note that diag is not a pointer to an array, but merely a 3797 pointer to a single value. 3798 3799 Notes: 3800 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 3801 but does not release memory. For the dense and block diagonal 3802 formats this does not alter the nonzero structure. 3803 3804 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 3805 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 3806 merely zeroed. 3807 3808 The user can set a value in the diagonal entry (or for the AIJ and 3809 row formats can optionally remove the main diagonal entry from the 3810 nonzero structure as well, by passing a null pointer (PETSC_NULL 3811 in C or PETSC_NULL_SCALAR in Fortran) as the final argument). 3812 3813 For the parallel case, all processes that share the matrix (i.e., 3814 those in the communicator used for matrix creation) MUST call this 3815 routine, regardless of whether any rows being zeroed are owned by 3816 them. 3817 3818 Each processor should list the rows that IT wants zeroed 3819 3820 Level: intermediate 3821 3822 Concepts: matrices^zeroing rows 3823 3824 .seealso: MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 3825 @*/ 3826 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,IS is,const PetscScalar *diag) 3827 { 3828 PetscErrorCode ierr; 3829 3830 PetscFunctionBegin; 3831 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3832 PetscValidType(mat,1); 3833 PetscValidHeaderSpecific(is,IS_COOKIE,2); 3834 if (diag) PetscValidScalarPointer(diag,3); 3835 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3836 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3837 if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 3838 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3839 3840 ierr = (*mat->ops->zerorows)(mat,is,diag);CHKERRQ(ierr); 3841 ierr = MatView_Private(mat);CHKERRQ(ierr); 3842 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3843 PetscFunctionReturn(0); 3844 } 3845 3846 #undef __FUNCT__ 3847 #define __FUNCT__ "MatZeroRowsLocal" 3848 /*@C 3849 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 3850 of a set of rows of a matrix; using local numbering of rows. 3851 3852 Collective on Mat 3853 3854 Input Parameters: 3855 + mat - the matrix 3856 . is - index set of rows to remove 3857 - diag - pointer to value put in all diagonals of eliminated rows. 3858 Note that diag is not a pointer to an array, but merely a 3859 pointer to a single value. 3860 3861 Notes: 3862 Before calling MatZeroRowsLocal(), the user must first set the 3863 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 3864 3865 For the AIJ matrix formats this removes the old nonzero structure, 3866 but does not release memory. For the dense and block diagonal 3867 formats this does not alter the nonzero structure. 3868 3869 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 3870 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 3871 merely zeroed. 3872 3873 The user can set a value in the diagonal entry (or for the AIJ and 3874 row formats can optionally remove the main diagonal entry from the 3875 nonzero structure as well, by passing a null pointer (PETSC_NULL 3876 in C or PETSC_NULL_SCALAR in Fortran) as the final argument). 3877 3878 Level: intermediate 3879 3880 Concepts: matrices^zeroing 3881 3882 .seealso: MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 3883 @*/ 3884 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,IS is,const PetscScalar *diag) 3885 { 3886 PetscErrorCode ierr; 3887 IS newis; 3888 3889 PetscFunctionBegin; 3890 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3891 PetscValidType(mat,1); 3892 PetscValidHeaderSpecific(is,IS_COOKIE,2); 3893 if (diag) PetscValidScalarPointer(diag,3); 3894 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3895 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3896 ierr = MatPreallocated(mat);CHKERRQ(ierr); 3897 3898 if (mat->ops->zerorowslocal) { 3899 ierr = (*mat->ops->zerorowslocal)(mat,is,diag);CHKERRQ(ierr); 3900 } else { 3901 if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 3902 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 3903 ierr = (*mat->ops->zerorows)(mat,newis,diag);CHKERRQ(ierr); 3904 ierr = ISDestroy(newis);CHKERRQ(ierr); 3905 } 3906 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 3907 PetscFunctionReturn(0); 3908 } 3909 3910 #undef __FUNCT__ 3911 #define __FUNCT__ "MatGetSize" 3912 /*@ 3913 MatGetSize - Returns the numbers of rows and columns in a matrix. 3914 3915 Not Collective 3916 3917 Input Parameter: 3918 . mat - the matrix 3919 3920 Output Parameters: 3921 + m - the number of global rows 3922 - n - the number of global columns 3923 3924 Note: both output parameters can be PETSC_NULL on input. 3925 3926 Level: beginner 3927 3928 Concepts: matrices^size 3929 3930 .seealso: MatGetLocalSize() 3931 @*/ 3932 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n) 3933 { 3934 PetscFunctionBegin; 3935 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3936 if (m) *m = mat->M; 3937 if (n) *n = mat->N; 3938 PetscFunctionReturn(0); 3939 } 3940 3941 #undef __FUNCT__ 3942 #define __FUNCT__ "MatGetLocalSize" 3943 /*@ 3944 MatGetLocalSize - Returns the number of rows and columns in a matrix 3945 stored locally. This information may be implementation dependent, so 3946 use with care. 3947 3948 Not Collective 3949 3950 Input Parameters: 3951 . mat - the matrix 3952 3953 Output Parameters: 3954 + m - the number of local rows 3955 - n - the number of local columns 3956 3957 Note: both output parameters can be PETSC_NULL on input. 3958 3959 Level: beginner 3960 3961 Concepts: matrices^local size 3962 3963 .seealso: MatGetSize() 3964 @*/ 3965 PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n) 3966 { 3967 PetscFunctionBegin; 3968 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 3969 if (m) PetscValidIntPointer(m,2); 3970 if (n) PetscValidIntPointer(n,3); 3971 if (m) *m = mat->m; 3972 if (n) *n = mat->n; 3973 PetscFunctionReturn(0); 3974 } 3975 3976 #undef __FUNCT__ 3977 #define __FUNCT__ "MatGetOwnershipRange" 3978 /*@ 3979 MatGetOwnershipRange - Returns the range of matrix rows owned by 3980 this processor, assuming that the matrix is laid out with the first 3981 n1 rows on the first processor, the next n2 rows on the second, etc. 3982 For certain parallel layouts this range may not be well defined. 3983 3984 Not Collective 3985 3986 Input Parameters: 3987 . mat - the matrix 3988 3989 Output Parameters: 3990 + m - the global index of the first local row 3991 - n - one more than the global index of the last local row 3992 3993 Note: both output parameters can be PETSC_NULL on input. 3994 3995 Level: beginner 3996 3997 Concepts: matrices^row ownership 3998 @*/ 3999 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n) 4000 { 4001 PetscErrorCode ierr; 4002 4003 PetscFunctionBegin; 4004 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4005 PetscValidType(mat,1); 4006 if (m) PetscValidIntPointer(m,2); 4007 if (n) PetscValidIntPointer(n,3); 4008 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4009 ierr = PetscMapGetLocalRange(mat->rmap,m,n);CHKERRQ(ierr); 4010 PetscFunctionReturn(0); 4011 } 4012 4013 #undef __FUNCT__ 4014 #define __FUNCT__ "MatILUFactorSymbolic" 4015 /*@ 4016 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 4017 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 4018 to complete the factorization. 4019 4020 Collective on Mat 4021 4022 Input Parameters: 4023 + mat - the matrix 4024 . row - row permutation 4025 . column - column permutation 4026 - info - structure containing 4027 $ levels - number of levels of fill. 4028 $ expected fill - as ratio of original fill. 4029 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 4030 missing diagonal entries) 4031 4032 Output Parameters: 4033 . fact - new matrix that has been symbolically factored 4034 4035 Notes: 4036 See the users manual for additional information about 4037 choosing the fill factor for better efficiency. 4038 4039 Most users should employ the simplified KSP interface for linear solvers 4040 instead of working directly with matrix algebra routines such as this. 4041 See, e.g., KSPCreate(). 4042 4043 Level: developer 4044 4045 Concepts: matrices^symbolic LU factorization 4046 Concepts: matrices^factorization 4047 Concepts: LU^symbolic factorization 4048 4049 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 4050 MatGetOrdering(), MatFactorInfo 4051 4052 @*/ 4053 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat mat,IS row,IS col,MatFactorInfo *info,Mat *fact) 4054 { 4055 PetscErrorCode ierr; 4056 4057 PetscFunctionBegin; 4058 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4059 PetscValidType(mat,1); 4060 PetscValidHeaderSpecific(row,IS_COOKIE,2); 4061 PetscValidHeaderSpecific(col,IS_COOKIE,3); 4062 PetscValidPointer(info,4); 4063 PetscValidPointer(fact,5); 4064 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels); 4065 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill); 4066 if (!mat->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",mat->type_name); 4067 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4068 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4069 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4070 4071 ierr = PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4072 ierr = (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 4073 ierr = PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 4074 PetscFunctionReturn(0); 4075 } 4076 4077 #undef __FUNCT__ 4078 #define __FUNCT__ "MatICCFactorSymbolic" 4079 /*@ 4080 MatICCFactorSymbolic - Performs symbolic incomplete 4081 Cholesky factorization for a symmetric matrix. Use 4082 MatCholeskyFactorNumeric() to complete the factorization. 4083 4084 Collective on Mat 4085 4086 Input Parameters: 4087 + mat - the matrix 4088 . perm - row and column permutation 4089 - info - structure containing 4090 $ levels - number of levels of fill. 4091 $ expected fill - as ratio of original fill. 4092 4093 Output Parameter: 4094 . fact - the factored matrix 4095 4096 Notes: 4097 Currently only no-fill factorization is supported. 4098 4099 Most users should employ the simplified KSP interface for linear solvers 4100 instead of working directly with matrix algebra routines such as this. 4101 See, e.g., KSPCreate(). 4102 4103 Level: developer 4104 4105 Concepts: matrices^symbolic incomplete Cholesky factorization 4106 Concepts: matrices^factorization 4107 Concepts: Cholsky^symbolic factorization 4108 4109 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 4110 @*/ 4111 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat mat,IS perm,MatFactorInfo *info,Mat *fact) 4112 { 4113 PetscErrorCode ierr; 4114 4115 PetscFunctionBegin; 4116 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4117 PetscValidType(mat,1); 4118 PetscValidHeaderSpecific(perm,IS_COOKIE,2); 4119 PetscValidPointer(info,3); 4120 PetscValidPointer(fact,4); 4121 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4122 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels); 4123 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill); 4124 if (!mat->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",mat->type_name); 4125 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4126 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4127 4128 ierr = PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4129 ierr = (*mat->ops->iccfactorsymbolic)(mat,perm,info,fact);CHKERRQ(ierr); 4130 ierr = PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 4131 PetscFunctionReturn(0); 4132 } 4133 4134 #undef __FUNCT__ 4135 #define __FUNCT__ "MatGetArray" 4136 /*@C 4137 MatGetArray - Returns a pointer to the element values in the matrix. 4138 The result of this routine is dependent on the underlying matrix data 4139 structure, and may not even work for certain matrix types. You MUST 4140 call MatRestoreArray() when you no longer need to access the array. 4141 4142 Not Collective 4143 4144 Input Parameter: 4145 . mat - the matrix 4146 4147 Output Parameter: 4148 . v - the location of the values 4149 4150 4151 Fortran Note: 4152 This routine is used differently from Fortran, e.g., 4153 .vb 4154 Mat mat 4155 PetscScalar mat_array(1) 4156 PetscOffset i_mat 4157 PetscErrorCode ierr 4158 call MatGetArray(mat,mat_array,i_mat,ierr) 4159 4160 C Access first local entry in matrix; note that array is 4161 C treated as one dimensional 4162 value = mat_array(i_mat + 1) 4163 4164 [... other code ...] 4165 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4166 .ve 4167 4168 See the Fortran chapter of the users manual and 4169 petsc/src/mat/examples/tests for details. 4170 4171 Level: advanced 4172 4173 Concepts: matrices^access array 4174 4175 .seealso: MatRestoreArray(), MatGetArrayF90() 4176 @*/ 4177 PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[]) 4178 { 4179 PetscErrorCode ierr; 4180 4181 PetscFunctionBegin; 4182 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4183 PetscValidType(mat,1); 4184 PetscValidPointer(v,2); 4185 if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4186 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4187 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 4188 PetscFunctionReturn(0); 4189 } 4190 4191 #undef __FUNCT__ 4192 #define __FUNCT__ "MatRestoreArray" 4193 /*@C 4194 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 4195 4196 Not Collective 4197 4198 Input Parameter: 4199 + mat - the matrix 4200 - v - the location of the values 4201 4202 Fortran Note: 4203 This routine is used differently from Fortran, e.g., 4204 .vb 4205 Mat mat 4206 PetscScalar mat_array(1) 4207 PetscOffset i_mat 4208 PetscErrorCode ierr 4209 call MatGetArray(mat,mat_array,i_mat,ierr) 4210 4211 C Access first local entry in matrix; note that array is 4212 C treated as one dimensional 4213 value = mat_array(i_mat + 1) 4214 4215 [... other code ...] 4216 call MatRestoreArray(mat,mat_array,i_mat,ierr) 4217 .ve 4218 4219 See the Fortran chapter of the users manual and 4220 petsc/src/mat/examples/tests for details 4221 4222 Level: advanced 4223 4224 .seealso: MatGetArray(), MatRestoreArrayF90() 4225 @*/ 4226 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[]) 4227 { 4228 PetscErrorCode ierr; 4229 4230 PetscFunctionBegin; 4231 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4232 PetscValidType(mat,1); 4233 PetscValidPointer(v,2); 4234 #if defined(PETSC_USE_DEBUG) 4235 CHKMEMQ; 4236 #endif 4237 if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4238 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 4239 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4240 PetscFunctionReturn(0); 4241 } 4242 4243 #undef __FUNCT__ 4244 #define __FUNCT__ "MatGetSubMatrices" 4245 /*@C 4246 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 4247 points to an array of valid matrices, they may be reused to store the new 4248 submatrices. 4249 4250 Collective on Mat 4251 4252 Input Parameters: 4253 + mat - the matrix 4254 . n - the number of submatrixes to be extracted (on this processor, may be zero) 4255 . irow, icol - index sets of rows and columns to extract 4256 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 4257 4258 Output Parameter: 4259 . submat - the array of submatrices 4260 4261 Notes: 4262 MatGetSubMatrices() can extract only sequential submatrices 4263 (from both sequential and parallel matrices). Use MatGetSubMatrix() 4264 to extract a parallel submatrix. 4265 4266 When extracting submatrices from a parallel matrix, each processor can 4267 form a different submatrix by setting the rows and columns of its 4268 individual index sets according to the local submatrix desired. 4269 4270 When finished using the submatrices, the user should destroy 4271 them with MatDestroyMatrices(). 4272 4273 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 4274 original matrix has not changed from that last call to MatGetSubMatrices(). 4275 4276 This routine creates the matrices in submat; you should NOT create them before 4277 calling it. It also allocates the array of matrix pointers submat. 4278 4279 For BAIJ matrices the index sets must respect the block structure, that is if they 4280 request one row/column in a block, they must request all rows/columns that are in 4281 that block. For example, if the block size is 2 you cannot request just row 0 and 4282 column 0. 4283 4284 Fortran Note: 4285 The Fortran interface is slightly different from that given below; it 4286 requires one to pass in as submat a Mat (integer) array of size at least m. 4287 4288 Level: advanced 4289 4290 Concepts: matrices^accessing submatrices 4291 Concepts: submatrices 4292 4293 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal() 4294 @*/ 4295 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[]) 4296 { 4297 PetscErrorCode ierr; 4298 PetscInt i; 4299 PetscTruth eq; 4300 4301 PetscFunctionBegin; 4302 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4303 PetscValidType(mat,1); 4304 if (n) { 4305 PetscValidPointer(irow,3); 4306 PetscValidHeaderSpecific(*irow,IS_COOKIE,3); 4307 PetscValidPointer(icol,4); 4308 PetscValidHeaderSpecific(*icol,IS_COOKIE,4); 4309 } 4310 PetscValidPointer(submat,6); 4311 if (n && scall == MAT_REUSE_MATRIX) { 4312 PetscValidPointer(*submat,6); 4313 PetscValidHeaderSpecific(**submat,MAT_COOKIE,6); 4314 } 4315 if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4316 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4317 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4318 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4319 4320 ierr = PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4321 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 4322 ierr = PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 4323 for (i=0; i<n; i++) { 4324 if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) { 4325 ierr = ISEqual(irow[i],icol[i],&eq);CHKERRQ(ierr); 4326 if (eq) { 4327 if (mat->symmetric){ 4328 ierr = MatSetOption((*submat)[i],MAT_SYMMETRIC);CHKERRQ(ierr); 4329 } else if (mat->hermitian) { 4330 ierr = MatSetOption((*submat)[i],MAT_HERMITIAN);CHKERRQ(ierr); 4331 } else if (mat->structurally_symmetric) { 4332 ierr = MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC);CHKERRQ(ierr); 4333 } 4334 } 4335 } 4336 } 4337 PetscFunctionReturn(0); 4338 } 4339 4340 #undef __FUNCT__ 4341 #define __FUNCT__ "MatDestroyMatrices" 4342 /*@C 4343 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 4344 4345 Collective on Mat 4346 4347 Input Parameters: 4348 + n - the number of local matrices 4349 - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling 4350 sequence of MatGetSubMatrices()) 4351 4352 Level: advanced 4353 4354 Notes: Frees not only the matrices, but also the array that contains the matrices 4355 4356 .seealso: MatGetSubMatrices() 4357 @*/ 4358 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[]) 4359 { 4360 PetscErrorCode ierr; 4361 PetscInt i; 4362 4363 PetscFunctionBegin; 4364 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n); 4365 PetscValidPointer(mat,2); 4366 for (i=0; i<n; i++) { 4367 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 4368 } 4369 /* memory is allocated even if n = 0 */ 4370 ierr = PetscFree(*mat);CHKERRQ(ierr); 4371 PetscFunctionReturn(0); 4372 } 4373 4374 #undef __FUNCT__ 4375 #define __FUNCT__ "MatIncreaseOverlap" 4376 /*@ 4377 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 4378 replaces the index sets by larger ones that represent submatrices with 4379 additional overlap. 4380 4381 Collective on Mat 4382 4383 Input Parameters: 4384 + mat - the matrix 4385 . n - the number of index sets 4386 . is - the array of index sets (these index sets will changed during the call) 4387 - ov - the additional overlap requested 4388 4389 Level: developer 4390 4391 Concepts: overlap 4392 Concepts: ASM^computing overlap 4393 4394 .seealso: MatGetSubMatrices() 4395 @*/ 4396 PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov) 4397 { 4398 PetscErrorCode ierr; 4399 4400 PetscFunctionBegin; 4401 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4402 PetscValidType(mat,1); 4403 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n); 4404 if (n) { 4405 PetscValidPointer(is,3); 4406 PetscValidHeaderSpecific(*is,IS_COOKIE,3); 4407 } 4408 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4409 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4410 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4411 4412 if (!ov) PetscFunctionReturn(0); 4413 if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4414 ierr = PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4415 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 4416 ierr = PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 4417 PetscFunctionReturn(0); 4418 } 4419 4420 #undef __FUNCT__ 4421 #define __FUNCT__ "MatPrintHelp" 4422 /*@ 4423 MatPrintHelp - Prints all the options for the matrix. 4424 4425 Collective on Mat 4426 4427 Input Parameter: 4428 . mat - the matrix 4429 4430 Options Database Keys: 4431 + -help - Prints matrix options 4432 - -h - Prints matrix options 4433 4434 Level: developer 4435 4436 .seealso: MatCreate(), MatCreateXXX() 4437 @*/ 4438 PetscErrorCode PETSCMAT_DLLEXPORT MatPrintHelp(Mat mat) 4439 { 4440 static PetscTruth called = PETSC_FALSE; 4441 PetscErrorCode ierr; 4442 4443 PetscFunctionBegin; 4444 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4445 PetscValidType(mat,1); 4446 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4447 4448 if (!called) { 4449 if (mat->ops->printhelp) { 4450 ierr = (*mat->ops->printhelp)(mat);CHKERRQ(ierr); 4451 } 4452 called = PETSC_TRUE; 4453 } 4454 PetscFunctionReturn(0); 4455 } 4456 4457 #undef __FUNCT__ 4458 #define __FUNCT__ "MatGetBlockSize" 4459 /*@ 4460 MatGetBlockSize - Returns the matrix block size; useful especially for the 4461 block row and block diagonal formats. 4462 4463 Not Collective 4464 4465 Input Parameter: 4466 . mat - the matrix 4467 4468 Output Parameter: 4469 . bs - block size 4470 4471 Notes: 4472 Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG. 4473 Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ 4474 4475 Level: intermediate 4476 4477 Concepts: matrices^block size 4478 4479 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag() 4480 @*/ 4481 PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs) 4482 { 4483 PetscErrorCode ierr; 4484 4485 PetscFunctionBegin; 4486 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4487 PetscValidType(mat,1); 4488 PetscValidIntPointer(bs,2); 4489 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4490 *bs = mat->bs; 4491 PetscFunctionReturn(0); 4492 } 4493 4494 #undef __FUNCT__ 4495 #define __FUNCT__ "MatSetBlockSize" 4496 /*@ 4497 MatSetBlockSize - Sets the matrix block size; for many matrix types you 4498 cannot use this and MUST set the blocksize when you preallocate the matrix 4499 4500 Not Collective 4501 4502 Input Parameters: 4503 + mat - the matrix 4504 - bs - block size 4505 4506 Notes: 4507 Only works for shell and AIJ matrices 4508 4509 Level: intermediate 4510 4511 Concepts: matrices^block size 4512 4513 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag(), MatGetBlockSize() 4514 @*/ 4515 PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs) 4516 { 4517 PetscErrorCode ierr; 4518 4519 PetscFunctionBegin; 4520 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4521 PetscValidType(mat,1); 4522 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4523 if (mat->ops->setblocksize) { 4524 mat->bs = bs; 4525 ierr = (*mat->ops->setblocksize)(mat,bs);CHKERRQ(ierr); 4526 } else { 4527 SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",mat->type_name); 4528 } 4529 PetscFunctionReturn(0); 4530 } 4531 4532 #undef __FUNCT__ 4533 #define __FUNCT__ "MatGetRowIJ" 4534 /*@C 4535 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 4536 4537 Collective on Mat 4538 4539 Input Parameters: 4540 + mat - the matrix 4541 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 4542 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 4543 symmetrized 4544 4545 Output Parameters: 4546 + n - number of rows in the (possibly compressed) matrix 4547 . ia - the row pointers 4548 . ja - the column indices 4549 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 4550 4551 Level: developer 4552 4553 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 4554 @*/ 4555 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 4556 { 4557 PetscErrorCode ierr; 4558 4559 PetscFunctionBegin; 4560 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4561 PetscValidType(mat,1); 4562 PetscValidIntPointer(n,4); 4563 if (ia) PetscValidIntPointer(ia,5); 4564 if (ja) PetscValidIntPointer(ja,6); 4565 PetscValidIntPointer(done,7); 4566 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4567 if (!mat->ops->getrowij) *done = PETSC_FALSE; 4568 else { 4569 *done = PETSC_TRUE; 4570 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 4571 } 4572 PetscFunctionReturn(0); 4573 } 4574 4575 #undef __FUNCT__ 4576 #define __FUNCT__ "MatGetColumnIJ" 4577 /*@C 4578 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 4579 4580 Collective on Mat 4581 4582 Input Parameters: 4583 + mat - the matrix 4584 . shift - 1 or zero indicating we want the indices starting at 0 or 1 4585 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 4586 symmetrized 4587 4588 Output Parameters: 4589 + n - number of columns in the (possibly compressed) matrix 4590 . ia - the column pointers 4591 . ja - the row indices 4592 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 4593 4594 Level: developer 4595 4596 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 4597 @*/ 4598 PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 4599 { 4600 PetscErrorCode ierr; 4601 4602 PetscFunctionBegin; 4603 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4604 PetscValidType(mat,1); 4605 PetscValidIntPointer(n,4); 4606 if (ia) PetscValidIntPointer(ia,5); 4607 if (ja) PetscValidIntPointer(ja,6); 4608 PetscValidIntPointer(done,7); 4609 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4610 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 4611 else { 4612 *done = PETSC_TRUE; 4613 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 4614 } 4615 PetscFunctionReturn(0); 4616 } 4617 4618 #undef __FUNCT__ 4619 #define __FUNCT__ "MatRestoreRowIJ" 4620 /*@C 4621 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 4622 MatGetRowIJ(). 4623 4624 Collective on Mat 4625 4626 Input Parameters: 4627 + mat - the matrix 4628 . shift - 1 or zero indicating we want the indices starting at 0 or 1 4629 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 4630 symmetrized 4631 4632 Output Parameters: 4633 + n - size of (possibly compressed) matrix 4634 . ia - the row pointers 4635 . ja - the column indices 4636 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 4637 4638 Level: developer 4639 4640 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 4641 @*/ 4642 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 4643 { 4644 PetscErrorCode ierr; 4645 4646 PetscFunctionBegin; 4647 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4648 PetscValidType(mat,1); 4649 if (ia) PetscValidIntPointer(ia,5); 4650 if (ja) PetscValidIntPointer(ja,6); 4651 PetscValidIntPointer(done,7); 4652 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4653 4654 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 4655 else { 4656 *done = PETSC_TRUE; 4657 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 4658 } 4659 PetscFunctionReturn(0); 4660 } 4661 4662 #undef __FUNCT__ 4663 #define __FUNCT__ "MatRestoreColumnIJ" 4664 /*@C 4665 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 4666 MatGetColumnIJ(). 4667 4668 Collective on Mat 4669 4670 Input Parameters: 4671 + mat - the matrix 4672 . shift - 1 or zero indicating we want the indices starting at 0 or 1 4673 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 4674 symmetrized 4675 4676 Output Parameters: 4677 + n - size of (possibly compressed) matrix 4678 . ia - the column pointers 4679 . ja - the row indices 4680 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 4681 4682 Level: developer 4683 4684 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 4685 @*/ 4686 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 4687 { 4688 PetscErrorCode ierr; 4689 4690 PetscFunctionBegin; 4691 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4692 PetscValidType(mat,1); 4693 if (ia) PetscValidIntPointer(ia,5); 4694 if (ja) PetscValidIntPointer(ja,6); 4695 PetscValidIntPointer(done,7); 4696 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4697 4698 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 4699 else { 4700 *done = PETSC_TRUE; 4701 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 4702 } 4703 PetscFunctionReturn(0); 4704 } 4705 4706 #undef __FUNCT__ 4707 #define __FUNCT__ "MatColoringPatch" 4708 /*@C 4709 MatColoringPatch -Used inside matrix coloring routines that 4710 use MatGetRowIJ() and/or MatGetColumnIJ(). 4711 4712 Collective on Mat 4713 4714 Input Parameters: 4715 + mat - the matrix 4716 . n - number of colors 4717 - colorarray - array indicating color for each column 4718 4719 Output Parameters: 4720 . iscoloring - coloring generated using colorarray information 4721 4722 Level: developer 4723 4724 .seealso: MatGetRowIJ(), MatGetColumnIJ() 4725 4726 @*/ 4727 PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt n,PetscInt ncolors,ISColoringValue colorarray[],ISColoring *iscoloring) 4728 { 4729 PetscErrorCode ierr; 4730 4731 PetscFunctionBegin; 4732 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4733 PetscValidType(mat,1); 4734 PetscValidIntPointer(colorarray,4); 4735 PetscValidPointer(iscoloring,5); 4736 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4737 4738 if (!mat->ops->coloringpatch){ 4739 ierr = ISColoringCreate(mat->comm,n,colorarray,iscoloring);CHKERRQ(ierr); 4740 } else { 4741 ierr = (*mat->ops->coloringpatch)(mat,n,ncolors,colorarray,iscoloring);CHKERRQ(ierr); 4742 } 4743 PetscFunctionReturn(0); 4744 } 4745 4746 4747 #undef __FUNCT__ 4748 #define __FUNCT__ "MatSetUnfactored" 4749 /*@ 4750 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 4751 4752 Collective on Mat 4753 4754 Input Parameter: 4755 . mat - the factored matrix to be reset 4756 4757 Notes: 4758 This routine should be used only with factored matrices formed by in-place 4759 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 4760 format). This option can save memory, for example, when solving nonlinear 4761 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 4762 ILU(0) preconditioner. 4763 4764 Note that one can specify in-place ILU(0) factorization by calling 4765 .vb 4766 PCType(pc,PCILU); 4767 PCILUSeUseInPlace(pc); 4768 .ve 4769 or by using the options -pc_type ilu -pc_ilu_in_place 4770 4771 In-place factorization ILU(0) can also be used as a local 4772 solver for the blocks within the block Jacobi or additive Schwarz 4773 methods (runtime option: -sub_pc_ilu_in_place). See the discussion 4774 of these preconditioners in the users manual for details on setting 4775 local solver options. 4776 4777 Most users should employ the simplified KSP interface for linear solvers 4778 instead of working directly with matrix algebra routines such as this. 4779 See, e.g., KSPCreate(). 4780 4781 Level: developer 4782 4783 .seealso: PCILUSetUseInPlace(), PCLUSetUseInPlace() 4784 4785 Concepts: matrices^unfactored 4786 4787 @*/ 4788 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat) 4789 { 4790 PetscErrorCode ierr; 4791 4792 PetscFunctionBegin; 4793 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4794 PetscValidType(mat,1); 4795 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4796 mat->factor = 0; 4797 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 4798 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 4799 PetscFunctionReturn(0); 4800 } 4801 4802 /*MC 4803 MatGetArrayF90 - Accesses a matrix array from Fortran90. 4804 4805 Synopsis: 4806 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 4807 4808 Not collective 4809 4810 Input Parameter: 4811 . x - matrix 4812 4813 Output Parameters: 4814 + xx_v - the Fortran90 pointer to the array 4815 - ierr - error code 4816 4817 Example of Usage: 4818 .vb 4819 PetscScalar, pointer xx_v(:) 4820 .... 4821 call MatGetArrayF90(x,xx_v,ierr) 4822 a = xx_v(3) 4823 call MatRestoreArrayF90(x,xx_v,ierr) 4824 .ve 4825 4826 Notes: 4827 Not yet supported for all F90 compilers 4828 4829 Level: advanced 4830 4831 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 4832 4833 Concepts: matrices^accessing array 4834 4835 M*/ 4836 4837 /*MC 4838 MatRestoreArrayF90 - Restores a matrix array that has been 4839 accessed with MatGetArrayF90(). 4840 4841 Synopsis: 4842 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 4843 4844 Not collective 4845 4846 Input Parameters: 4847 + x - matrix 4848 - xx_v - the Fortran90 pointer to the array 4849 4850 Output Parameter: 4851 . ierr - error code 4852 4853 Example of Usage: 4854 .vb 4855 PetscScalar, pointer xx_v(:) 4856 .... 4857 call MatGetArrayF90(x,xx_v,ierr) 4858 a = xx_v(3) 4859 call MatRestoreArrayF90(x,xx_v,ierr) 4860 .ve 4861 4862 Notes: 4863 Not yet supported for all F90 compilers 4864 4865 Level: advanced 4866 4867 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 4868 4869 M*/ 4870 4871 4872 #undef __FUNCT__ 4873 #define __FUNCT__ "MatGetSubMatrix" 4874 /*@ 4875 MatGetSubMatrix - Gets a single submatrix on the same number of processors 4876 as the original matrix. 4877 4878 Collective on Mat 4879 4880 Input Parameters: 4881 + mat - the original matrix 4882 . isrow - rows this processor should obtain 4883 . iscol - columns for all processors you wish to keep 4884 . csize - number of columns "local" to this processor (does nothing for sequential 4885 matrices). This should match the result from VecGetLocalSize(x,...) if you 4886 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 4887 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 4888 4889 Output Parameter: 4890 . newmat - the new submatrix, of the same type as the old 4891 4892 Level: advanced 4893 4894 Notes: the iscol argument MUST be the same on each processor. You might be 4895 able to create the iscol argument with ISAllGather(). 4896 4897 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 4898 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 4899 to this routine with a mat of the same nonzero structure and with a cll of MAT_REUSE_MATRIX 4900 will reuse the matrix generated the first time. 4901 4902 Concepts: matrices^submatrices 4903 4904 .seealso: MatGetSubMatrices(), ISAllGather() 4905 @*/ 4906 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,PetscInt csize,MatReuse cll,Mat *newmat) 4907 { 4908 PetscErrorCode ierr; 4909 PetscMPIInt size; 4910 Mat *local; 4911 4912 PetscFunctionBegin; 4913 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4914 PetscValidHeaderSpecific(isrow,IS_COOKIE,2); 4915 PetscValidHeaderSpecific(iscol,IS_COOKIE,3); 4916 PetscValidPointer(newmat,6); 4917 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_COOKIE,6); 4918 PetscValidType(mat,1); 4919 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4920 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4921 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 4922 4923 /* if original matrix is on just one processor then use submatrix generated */ 4924 if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 4925 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 4926 PetscFunctionReturn(0); 4927 } else if (!mat->ops->getsubmatrix && size == 1) { 4928 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 4929 *newmat = *local; 4930 ierr = PetscFree(local);CHKERRQ(ierr); 4931 PetscFunctionReturn(0); 4932 } 4933 4934 if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 4935 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);CHKERRQ(ierr); 4936 ierr = PetscObjectStateIncrease((PetscObject)*newmat);CHKERRQ(ierr); 4937 PetscFunctionReturn(0); 4938 } 4939 4940 #undef __FUNCT__ 4941 #define __FUNCT__ "MatGetPetscMaps" 4942 /*@C 4943 MatGetPetscMaps - Returns the maps associated with the matrix. 4944 4945 Not Collective 4946 4947 Input Parameter: 4948 . mat - the matrix 4949 4950 Output Parameters: 4951 + rmap - the row (right) map 4952 - cmap - the column (left) map 4953 4954 Level: developer 4955 4956 Concepts: maps^getting from matrix 4957 4958 @*/ 4959 PetscErrorCode PETSCMAT_DLLEXPORT MatGetPetscMaps(Mat mat,PetscMap *rmap,PetscMap *cmap) 4960 { 4961 PetscErrorCode ierr; 4962 4963 PetscFunctionBegin; 4964 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 4965 PetscValidType(mat,1); 4966 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4967 ierr = (*mat->ops->getmaps)(mat,rmap,cmap);CHKERRQ(ierr); 4968 PetscFunctionReturn(0); 4969 } 4970 4971 /* 4972 Version that works for all PETSc matrices 4973 */ 4974 #undef __FUNCT__ 4975 #define __FUNCT__ "MatGetPetscMaps_Petsc" 4976 PetscErrorCode MatGetPetscMaps_Petsc(Mat mat,PetscMap *rmap,PetscMap *cmap) 4977 { 4978 PetscFunctionBegin; 4979 if (rmap) *rmap = mat->rmap; 4980 if (cmap) *cmap = mat->cmap; 4981 PetscFunctionReturn(0); 4982 } 4983 4984 #undef __FUNCT__ 4985 #define __FUNCT__ "MatStashSetInitialSize" 4986 /*@ 4987 MatStashSetInitialSize - sets the sizes of the matrix stash, that is 4988 used during the assembly process to store values that belong to 4989 other processors. 4990 4991 Not Collective 4992 4993 Input Parameters: 4994 + mat - the matrix 4995 . size - the initial size of the stash. 4996 - bsize - the initial size of the block-stash(if used). 4997 4998 Options Database Keys: 4999 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 5000 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 5001 5002 Level: intermediate 5003 5004 Notes: 5005 The block-stash is used for values set with VecSetValuesBlocked() while 5006 the stash is used for values set with VecSetValues() 5007 5008 Run with the option -log_info and look for output of the form 5009 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 5010 to determine the appropriate value, MM, to use for size and 5011 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 5012 to determine the value, BMM to use for bsize 5013 5014 Concepts: stash^setting matrix size 5015 Concepts: matrices^stash 5016 5017 @*/ 5018 PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize) 5019 { 5020 PetscErrorCode ierr; 5021 5022 PetscFunctionBegin; 5023 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5024 PetscValidType(mat,1); 5025 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5026 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 5027 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 5028 PetscFunctionReturn(0); 5029 } 5030 5031 #undef __FUNCT__ 5032 #define __FUNCT__ "MatInterpolateAdd" 5033 /*@ 5034 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 5035 the matrix 5036 5037 Collective on Mat 5038 5039 Input Parameters: 5040 + mat - the matrix 5041 . x,y - the vectors 5042 - w - where the result is stored 5043 5044 Level: intermediate 5045 5046 Notes: 5047 w may be the same vector as y. 5048 5049 This allows one to use either the restriction or interpolation (its transpose) 5050 matrix to do the interpolation 5051 5052 Concepts: interpolation 5053 5054 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5055 5056 @*/ 5057 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 5058 { 5059 PetscErrorCode ierr; 5060 PetscInt M,N; 5061 5062 PetscFunctionBegin; 5063 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5064 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5065 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5066 PetscValidHeaderSpecific(w,VEC_COOKIE,4); 5067 PetscValidType(A,1); 5068 ierr = MatPreallocated(A);CHKERRQ(ierr); 5069 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5070 if (N > M) { 5071 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 5072 } else { 5073 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 5074 } 5075 PetscFunctionReturn(0); 5076 } 5077 5078 #undef __FUNCT__ 5079 #define __FUNCT__ "MatInterpolate" 5080 /*@ 5081 MatInterpolate - y = A*x or A'*x depending on the shape of 5082 the matrix 5083 5084 Collective on Mat 5085 5086 Input Parameters: 5087 + mat - the matrix 5088 - x,y - the vectors 5089 5090 Level: intermediate 5091 5092 Notes: 5093 This allows one to use either the restriction or interpolation (its transpose) 5094 matrix to do the interpolation 5095 5096 Concepts: matrices^interpolation 5097 5098 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 5099 5100 @*/ 5101 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y) 5102 { 5103 PetscErrorCode ierr; 5104 PetscInt M,N; 5105 5106 PetscFunctionBegin; 5107 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5108 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5109 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5110 PetscValidType(A,1); 5111 ierr = MatPreallocated(A);CHKERRQ(ierr); 5112 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5113 if (N > M) { 5114 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5115 } else { 5116 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5117 } 5118 PetscFunctionReturn(0); 5119 } 5120 5121 #undef __FUNCT__ 5122 #define __FUNCT__ "MatRestrict" 5123 /*@ 5124 MatRestrict - y = A*x or A'*x 5125 5126 Collective on Mat 5127 5128 Input Parameters: 5129 + mat - the matrix 5130 - x,y - the vectors 5131 5132 Level: intermediate 5133 5134 Notes: 5135 This allows one to use either the restriction or interpolation (its transpose) 5136 matrix to do the restriction 5137 5138 Concepts: matrices^restriction 5139 5140 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 5141 5142 @*/ 5143 PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y) 5144 { 5145 PetscErrorCode ierr; 5146 PetscInt M,N; 5147 5148 PetscFunctionBegin; 5149 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5150 PetscValidHeaderSpecific(x,VEC_COOKIE,2); 5151 PetscValidHeaderSpecific(y,VEC_COOKIE,3); 5152 PetscValidType(A,1); 5153 ierr = MatPreallocated(A);CHKERRQ(ierr); 5154 5155 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 5156 if (N > M) { 5157 ierr = MatMult(A,x,y);CHKERRQ(ierr); 5158 } else { 5159 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 5160 } 5161 PetscFunctionReturn(0); 5162 } 5163 5164 #undef __FUNCT__ 5165 #define __FUNCT__ "MatNullSpaceAttach" 5166 /*@C 5167 MatNullSpaceAttach - attaches a null space to a matrix. 5168 This null space will be removed from the resulting vector whenever 5169 MatMult() is called 5170 5171 Collective on Mat 5172 5173 Input Parameters: 5174 + mat - the matrix 5175 - nullsp - the null space object 5176 5177 Level: developer 5178 5179 Notes: 5180 Overwrites any previous null space that may have been attached 5181 5182 Concepts: null space^attaching to matrix 5183 5184 .seealso: MatCreate(), MatNullSpaceCreate() 5185 @*/ 5186 PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 5187 { 5188 PetscErrorCode ierr; 5189 5190 PetscFunctionBegin; 5191 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5192 PetscValidType(mat,1); 5193 PetscValidHeaderSpecific(nullsp,MAT_NULLSPACE_COOKIE,2); 5194 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5195 5196 if (mat->nullsp) { 5197 ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); 5198 } 5199 mat->nullsp = nullsp; 5200 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 5201 PetscFunctionReturn(0); 5202 } 5203 5204 #undef __FUNCT__ 5205 #define __FUNCT__ "MatICCFactor" 5206 /*@ 5207 MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix. 5208 5209 Collective on Mat 5210 5211 Input Parameters: 5212 + mat - the matrix 5213 . row - row/column permutation 5214 . fill - expected fill factor >= 1.0 5215 - level - level of fill, for ICC(k) 5216 5217 Notes: 5218 Probably really in-place only when level of fill is zero, otherwise allocates 5219 new space to store factored matrix and deletes previous memory. 5220 5221 Most users should employ the simplified KSP interface for linear solvers 5222 instead of working directly with matrix algebra routines such as this. 5223 See, e.g., KSPCreate(). 5224 5225 Level: developer 5226 5227 Concepts: matrices^incomplete Cholesky factorization 5228 Concepts: Cholesky factorization 5229 5230 .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 5231 @*/ 5232 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,MatFactorInfo* info) 5233 { 5234 PetscErrorCode ierr; 5235 5236 PetscFunctionBegin; 5237 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5238 PetscValidType(mat,1); 5239 if (row) PetscValidHeaderSpecific(row,IS_COOKIE,2); 5240 PetscValidPointer(info,3); 5241 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 5242 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5243 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5244 if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5245 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5246 ierr = (*mat->ops->iccfactor)(mat,row,info);CHKERRQ(ierr); 5247 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5248 PetscFunctionReturn(0); 5249 } 5250 5251 #undef __FUNCT__ 5252 #define __FUNCT__ "MatSetValuesAdic" 5253 /*@ 5254 MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix. 5255 5256 Not Collective 5257 5258 Input Parameters: 5259 + mat - the matrix 5260 - v - the values compute with ADIC 5261 5262 Level: developer 5263 5264 Notes: 5265 Must call MatSetColoring() before using this routine. Also this matrix must already 5266 have its nonzero pattern determined. 5267 5268 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5269 MatSetValues(), MatSetColoring(), MatSetValuesAdifor() 5270 @*/ 5271 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v) 5272 { 5273 PetscErrorCode ierr; 5274 5275 PetscFunctionBegin; 5276 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5277 PetscValidType(mat,1); 5278 PetscValidPointer(mat,2); 5279 5280 if (!mat->assembled) { 5281 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5282 } 5283 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5284 if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5285 ierr = (*mat->ops->setvaluesadic)(mat,v);CHKERRQ(ierr); 5286 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5287 ierr = MatView_Private(mat);CHKERRQ(ierr); 5288 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5289 PetscFunctionReturn(0); 5290 } 5291 5292 5293 #undef __FUNCT__ 5294 #define __FUNCT__ "MatSetColoring" 5295 /*@ 5296 MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic() 5297 5298 Not Collective 5299 5300 Input Parameters: 5301 + mat - the matrix 5302 - coloring - the coloring 5303 5304 Level: developer 5305 5306 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5307 MatSetValues(), MatSetValuesAdic() 5308 @*/ 5309 PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring) 5310 { 5311 PetscErrorCode ierr; 5312 5313 PetscFunctionBegin; 5314 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5315 PetscValidType(mat,1); 5316 PetscValidPointer(coloring,2); 5317 5318 if (!mat->assembled) { 5319 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5320 } 5321 if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5322 ierr = (*mat->ops->setcoloring)(mat,coloring);CHKERRQ(ierr); 5323 PetscFunctionReturn(0); 5324 } 5325 5326 #undef __FUNCT__ 5327 #define __FUNCT__ "MatSetValuesAdifor" 5328 /*@ 5329 MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix. 5330 5331 Not Collective 5332 5333 Input Parameters: 5334 + mat - the matrix 5335 . nl - leading dimension of v 5336 - v - the values compute with ADIFOR 5337 5338 Level: developer 5339 5340 Notes: 5341 Must call MatSetColoring() before using this routine. Also this matrix must already 5342 have its nonzero pattern determined. 5343 5344 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 5345 MatSetValues(), MatSetColoring() 5346 @*/ 5347 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v) 5348 { 5349 PetscErrorCode ierr; 5350 5351 PetscFunctionBegin; 5352 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5353 PetscValidType(mat,1); 5354 PetscValidPointer(v,3); 5355 5356 if (!mat->assembled) { 5357 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5358 } 5359 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5360 if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5361 ierr = (*mat->ops->setvaluesadifor)(mat,nl,v);CHKERRQ(ierr); 5362 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 5363 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5364 PetscFunctionReturn(0); 5365 } 5366 5367 #undef __FUNCT__ 5368 #define __FUNCT__ "MatDiagonalScaleLocal" 5369 /*@ 5370 MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 5371 ghosted ones. 5372 5373 Not Collective 5374 5375 Input Parameters: 5376 + mat - the matrix 5377 - diag = the diagonal values, including ghost ones 5378 5379 Level: developer 5380 5381 Notes: Works only for MPIAIJ and MPIBAIJ matrices 5382 5383 .seealso: MatDiagonalScale() 5384 @*/ 5385 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag) 5386 { 5387 PetscErrorCode ierr; 5388 PetscMPIInt size; 5389 5390 PetscFunctionBegin; 5391 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5392 PetscValidHeaderSpecific(diag,VEC_COOKIE,2); 5393 PetscValidType(mat,1); 5394 5395 if (!mat->assembled) { 5396 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 5397 } 5398 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5399 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 5400 if (size == 1) { 5401 PetscInt n,m; 5402 ierr = VecGetSize(diag,&n);CHKERRQ(ierr); 5403 ierr = MatGetSize(mat,0,&m);CHKERRQ(ierr); 5404 if (m == n) { 5405 ierr = MatDiagonalScale(mat,0,diag);CHKERRQ(ierr); 5406 } else { 5407 SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions"); 5408 } 5409 } else { 5410 PetscErrorCode (*f)(Mat,Vec); 5411 ierr = PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);CHKERRQ(ierr); 5412 if (f) { 5413 ierr = (*f)(mat,diag);CHKERRQ(ierr); 5414 } else { 5415 SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices"); 5416 } 5417 } 5418 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 5419 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5420 PetscFunctionReturn(0); 5421 } 5422 5423 #undef __FUNCT__ 5424 #define __FUNCT__ "MatGetInertia" 5425 /*@ 5426 MatGetInertia - Gets the inertia from a factored matrix 5427 5428 Collective on Mat 5429 5430 Input Parameter: 5431 . mat - the matrix 5432 5433 Output Parameters: 5434 + nneg - number of negative eigenvalues 5435 . nzero - number of zero eigenvalues 5436 - npos - number of positive eigenvalues 5437 5438 Level: advanced 5439 5440 Notes: Matrix must have been factored by MatCholeskyFactor() 5441 5442 5443 @*/ 5444 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos) 5445 { 5446 PetscErrorCode ierr; 5447 5448 PetscFunctionBegin; 5449 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5450 PetscValidType(mat,1); 5451 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 5452 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled"); 5453 if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5454 ierr = (*mat->ops->getinertia)(mat,nneg,nzero,npos);CHKERRQ(ierr); 5455 PetscFunctionReturn(0); 5456 } 5457 5458 /* ----------------------------------------------------------------*/ 5459 #undef __FUNCT__ 5460 #define __FUNCT__ "MatSolves" 5461 /*@ 5462 MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors 5463 5464 Collective on Mat and Vecs 5465 5466 Input Parameters: 5467 + mat - the factored matrix 5468 - b - the right-hand-side vectors 5469 5470 Output Parameter: 5471 . x - the result vectors 5472 5473 Notes: 5474 The vectors b and x cannot be the same. I.e., one cannot 5475 call MatSolves(A,x,x). 5476 5477 Notes: 5478 Most users should employ the simplified KSP interface for linear solvers 5479 instead of working directly with matrix algebra routines such as this. 5480 See, e.g., KSPCreate(). 5481 5482 Level: developer 5483 5484 Concepts: matrices^triangular solves 5485 5486 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve() 5487 @*/ 5488 PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x) 5489 { 5490 PetscErrorCode ierr; 5491 5492 PetscFunctionBegin; 5493 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5494 PetscValidType(mat,1); 5495 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 5496 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 5497 if (!mat->M && !mat->N) PetscFunctionReturn(0); 5498 5499 if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",mat->type_name); 5500 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5501 ierr = PetscLogEventBegin(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 5502 ierr = (*mat->ops->solves)(mat,b,x);CHKERRQ(ierr); 5503 ierr = PetscLogEventEnd(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 5504 PetscFunctionReturn(0); 5505 } 5506 5507 #undef __FUNCT__ 5508 #define __FUNCT__ "MatIsSymmetric" 5509 /*@ 5510 MatIsSymmetric - Test whether a matrix is symmetric 5511 5512 Collective on Mat 5513 5514 Input Parameter: 5515 + A - the matrix to test 5516 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose) 5517 5518 Output Parameters: 5519 . flg - the result 5520 5521 Level: intermediate 5522 5523 Concepts: matrix^symmetry 5524 5525 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 5526 @*/ 5527 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg) 5528 { 5529 PetscErrorCode ierr; 5530 5531 PetscFunctionBegin; 5532 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5533 PetscValidPointer(flg,2); 5534 if (!A->symmetric_set) { 5535 if (!A->ops->issymmetric) { 5536 MatType mattype; 5537 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 5538 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 5539 } 5540 ierr = (*A->ops->issymmetric)(A,tol,&A->symmetric);CHKERRQ(ierr); 5541 A->symmetric_set = PETSC_TRUE; 5542 if (A->symmetric) { 5543 A->structurally_symmetric_set = PETSC_TRUE; 5544 A->structurally_symmetric = PETSC_TRUE; 5545 } 5546 } 5547 *flg = A->symmetric; 5548 PetscFunctionReturn(0); 5549 } 5550 5551 #undef __FUNCT__ 5552 #define __FUNCT__ "MatIsSymmetricKnown" 5553 /*@ 5554 MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric. 5555 5556 Collective on Mat 5557 5558 Input Parameter: 5559 . A - the matrix to check 5560 5561 Output Parameters: 5562 + set - if the symmetric flag is set (this tells you if the next flag is valid) 5563 - flg - the result 5564 5565 Level: advanced 5566 5567 Concepts: matrix^symmetry 5568 5569 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric() 5570 if you want it explicitly checked 5571 5572 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 5573 @*/ 5574 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg) 5575 { 5576 PetscFunctionBegin; 5577 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5578 PetscValidPointer(set,2); 5579 PetscValidPointer(flg,3); 5580 if (A->symmetric_set) { 5581 *set = PETSC_TRUE; 5582 *flg = A->symmetric; 5583 } else { 5584 *set = PETSC_FALSE; 5585 } 5586 PetscFunctionReturn(0); 5587 } 5588 5589 #undef __FUNCT__ 5590 #define __FUNCT__ "MatIsHermitianKnown" 5591 /*@ 5592 MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian. 5593 5594 Collective on Mat 5595 5596 Input Parameter: 5597 . A - the matrix to check 5598 5599 Output Parameters: 5600 + set - if the hermitian flag is set (this tells you if the next flag is valid) 5601 - flg - the result 5602 5603 Level: advanced 5604 5605 Concepts: matrix^symmetry 5606 5607 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian() 5608 if you want it explicitly checked 5609 5610 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 5611 @*/ 5612 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg) 5613 { 5614 PetscFunctionBegin; 5615 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5616 PetscValidPointer(set,2); 5617 PetscValidPointer(flg,3); 5618 if (A->hermitian_set) { 5619 *set = PETSC_TRUE; 5620 *flg = A->hermitian; 5621 } else { 5622 *set = PETSC_FALSE; 5623 } 5624 PetscFunctionReturn(0); 5625 } 5626 5627 #undef __FUNCT__ 5628 #define __FUNCT__ "MatIsStructurallySymmetric" 5629 /*@ 5630 MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric 5631 5632 Collective on Mat 5633 5634 Input Parameter: 5635 . A - the matrix to test 5636 5637 Output Parameters: 5638 . flg - the result 5639 5640 Level: intermediate 5641 5642 Concepts: matrix^symmetry 5643 5644 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption() 5645 @*/ 5646 PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg) 5647 { 5648 PetscErrorCode ierr; 5649 5650 PetscFunctionBegin; 5651 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5652 PetscValidPointer(flg,2); 5653 if (!A->structurally_symmetric_set) { 5654 if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric"); 5655 ierr = (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);CHKERRQ(ierr); 5656 A->structurally_symmetric_set = PETSC_TRUE; 5657 } 5658 *flg = A->structurally_symmetric; 5659 PetscFunctionReturn(0); 5660 } 5661 5662 #undef __FUNCT__ 5663 #define __FUNCT__ "MatIsHermitian" 5664 /*@ 5665 MatIsHermitian - Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose. 5666 5667 Collective on Mat 5668 5669 Input Parameter: 5670 . A - the matrix to test 5671 5672 Output Parameters: 5673 . flg - the result 5674 5675 Level: intermediate 5676 5677 Concepts: matrix^symmetry 5678 5679 .seealso: MatTranspose(), MatIsTranspose(), MatIsSymmetric(), MatIsStructurallySymmetric(), MatSetOption() 5680 @*/ 5681 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscTruth *flg) 5682 { 5683 PetscErrorCode ierr; 5684 5685 PetscFunctionBegin; 5686 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5687 PetscValidPointer(flg,2); 5688 if (!A->hermitian_set) { 5689 if (!A->ops->ishermitian) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for being Hermitian"); 5690 ierr = (*A->ops->ishermitian)(A,&A->hermitian);CHKERRQ(ierr); 5691 A->hermitian_set = PETSC_TRUE; 5692 if (A->hermitian) { 5693 A->structurally_symmetric_set = PETSC_TRUE; 5694 A->structurally_symmetric = PETSC_TRUE; 5695 } 5696 } 5697 *flg = A->hermitian; 5698 PetscFunctionReturn(0); 5699 } 5700 5701 #undef __FUNCT__ 5702 #define __FUNCT__ "MatStashGetInfo" 5703 extern PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*); 5704 /*@ 5705 MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need 5706 to be communicated to other processors during the MatAssemblyBegin/End() process 5707 5708 Not collective 5709 5710 Input Parameter: 5711 . vec - the vector 5712 5713 Output Parameters: 5714 + nstash - the size of the stash 5715 . reallocs - the number of additional mallocs incurred. 5716 . bnstash - the size of the block stash 5717 - breallocs - the number of additional mallocs incurred.in the block stash 5718 5719 Level: advanced 5720 5721 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize() 5722 5723 @*/ 5724 PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc) 5725 { 5726 PetscErrorCode ierr; 5727 PetscFunctionBegin; 5728 ierr = MatStashGetInfo_Private(&mat->stash,nstash,reallocs);CHKERRQ(ierr); 5729 ierr = MatStashGetInfo_Private(&mat->bstash,nstash,reallocs);CHKERRQ(ierr); 5730 PetscFunctionReturn(0); 5731 } 5732 5733 #undef __FUNCT__ 5734 #define __FUNCT__ "MatGetVecs" 5735 /*@ 5736 MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 5737 parallel layout 5738 5739 Collective on Mat 5740 5741 Input Parameter: 5742 . mat - the matrix 5743 5744 Output Parameter: 5745 + right - (optional) vector that the matrix can be multiplied against 5746 - left - (optional) vector that the matrix vector product can be stored in 5747 5748 Level: advanced 5749 5750 .seealso: MatCreate() 5751 @*/ 5752 PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left) 5753 { 5754 PetscErrorCode ierr; 5755 5756 PetscFunctionBegin; 5757 PetscValidHeaderSpecific(mat,MAT_COOKIE,1); 5758 PetscValidType(mat,1); 5759 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5760 if (mat->ops->getvecs) { 5761 ierr = (*mat->ops->getvecs)(mat,right,left);CHKERRQ(ierr); 5762 } else { 5763 PetscMPIInt size; 5764 ierr = MPI_Comm_size(mat->comm, &size);CHKERRQ(ierr); 5765 if (right) { 5766 ierr = VecCreate(mat->comm,right);CHKERRQ(ierr); 5767 ierr = VecSetSizes(*right,mat->n,PETSC_DETERMINE);CHKERRQ(ierr); 5768 if (size > 1) {ierr = VecSetType(*right,VECMPI);CHKERRQ(ierr);} 5769 else {ierr = VecSetType(*right,VECSEQ);CHKERRQ(ierr);} 5770 } 5771 if (left) { 5772 ierr = VecCreate(mat->comm,left);CHKERRQ(ierr); 5773 ierr = VecSetSizes(*left,mat->m,PETSC_DETERMINE);CHKERRQ(ierr); 5774 if (size > 1) {ierr = VecSetType(*left,VECMPI);CHKERRQ(ierr);} 5775 else {ierr = VecSetType(*left,VECSEQ);CHKERRQ(ierr);} 5776 } 5777 } 5778 if (right) {ierr = VecSetBlockSize(*right,mat->bs);CHKERRQ(ierr);} 5779 if (left) {ierr = VecSetBlockSize(*left,mat->bs);CHKERRQ(ierr);} 5780 PetscFunctionReturn(0); 5781 } 5782 5783 #undef __FUNCT__ 5784 #define __FUNCT__ "MatFactorInfoInitialize" 5785 /*@C 5786 MatFactorInfoInitialize - Initializes a MatFactorInfo data structure 5787 with default values. 5788 5789 Not Collective 5790 5791 Input Parameters: 5792 . info - the MatFactorInfo data structure 5793 5794 5795 Notes: The solvers are generally used through the KSP and PC objects, for example 5796 PCLU, PCILU, PCCHOLESKY, PCICC 5797 5798 Level: developer 5799 5800 .seealso: MatFactorInfo 5801 @*/ 5802 5803 PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info) 5804 { 5805 PetscErrorCode ierr; 5806 5807 PetscFunctionBegin; 5808 ierr = PetscMemzero(info,sizeof(MatFactorInfo));CHKERRQ(ierr); 5809 PetscFunctionReturn(0); 5810 } 5811 5812 #undef __FUNCT__ 5813 #define __FUNCT__ "MatPtAP" 5814 /*@C 5815 MatPtAP - Creates the matrix projection C = P^T * A * P 5816 5817 Collective on Mat 5818 5819 Input Parameters: 5820 + A - the matrix 5821 . P - the projection matrix 5822 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5823 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)) 5824 5825 Output Parameters: 5826 . C - the product matrix 5827 5828 Notes: 5829 C will be created and must be destroyed by the user with MatDestroy(). 5830 5831 This routine is currently only implemented for pairs of AIJ matrices and classes 5832 which inherit from AIJ. 5833 5834 Level: intermediate 5835 5836 .seealso: MatPtAPSymbolic(),MatPtAPNumeric(),MatMatMult() 5837 @*/ 5838 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C) 5839 { 5840 PetscErrorCode ierr; 5841 5842 PetscFunctionBegin; 5843 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5844 PetscValidType(A,1); 5845 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5846 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5847 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 5848 PetscValidType(P,2); 5849 MatPreallocated(P); 5850 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5851 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5852 PetscValidPointer(C,3); 5853 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 5854 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill); 5855 ierr = MatPreallocated(A);CHKERRQ(ierr); 5856 5857 ierr = PetscLogEventBegin(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 5858 ierr = (*A->ops->ptap)(A,P,scall,fill,C);CHKERRQ(ierr); 5859 ierr = PetscLogEventEnd(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 5860 5861 PetscFunctionReturn(0); 5862 } 5863 5864 #undef __FUNCT__ 5865 #define __FUNCT__ "MatPtAPNumeric" 5866 /*@C 5867 MatPtAPNumeric - Computes the matrix projection C = P^T * A * P 5868 5869 Collective on Mat 5870 5871 Input Parameters: 5872 + A - the matrix 5873 - P - the projection matrix 5874 5875 Output Parameters: 5876 . C - the product matrix 5877 5878 Notes: 5879 C must have been created by calling MatPtAPSymbolic and must be destroyed by 5880 the user using MatDeatroy(). 5881 5882 This routine is currently only implemented for pairs of AIJ matrices and classes 5883 which inherit from AIJ. C will be of type MATAIJ. 5884 5885 Level: intermediate 5886 5887 .seealso: MatPtAP(),MatPtAPSymbolic(),MatMatMultNumeric() 5888 @*/ 5889 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C) 5890 { 5891 PetscErrorCode ierr; 5892 5893 PetscFunctionBegin; 5894 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5895 PetscValidType(A,1); 5896 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5897 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5898 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 5899 PetscValidType(P,2); 5900 MatPreallocated(P); 5901 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5902 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5903 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 5904 PetscValidType(C,3); 5905 MatPreallocated(C); 5906 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5907 if (P->N!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->M); 5908 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 5909 if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N); 5910 if (P->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->N,C->N); 5911 ierr = MatPreallocated(A);CHKERRQ(ierr); 5912 5913 ierr = PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 5914 ierr = (*A->ops->ptapnumeric)(A,P,C);CHKERRQ(ierr); 5915 ierr = PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 5916 PetscFunctionReturn(0); 5917 } 5918 5919 #undef __FUNCT__ 5920 #define __FUNCT__ "MatPtAPSymbolic" 5921 /*@C 5922 MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P 5923 5924 Collective on Mat 5925 5926 Input Parameters: 5927 + A - the matrix 5928 - P - the projection matrix 5929 5930 Output Parameters: 5931 . C - the (i,j) structure of the product matrix 5932 5933 Notes: 5934 C will be created and must be destroyed by the user with MatDestroy(). 5935 5936 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 5937 which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using 5938 this (i,j) structure by calling MatPtAPNumeric(). 5939 5940 Level: intermediate 5941 5942 .seealso: MatPtAP(),MatPtAPNumeric(),MatMatMultSymbolic() 5943 @*/ 5944 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C) 5945 { 5946 PetscErrorCode ierr; 5947 5948 PetscFunctionBegin; 5949 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 5950 PetscValidType(A,1); 5951 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5952 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5953 PetscValidHeaderSpecific(P,MAT_COOKIE,2); 5954 PetscValidType(P,2); 5955 MatPreallocated(P); 5956 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5957 if (P->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5958 PetscValidPointer(C,3); 5959 5960 if (P->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->M,A->N); 5961 if (A->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix 'A' must be square, %D != %D",A->M,A->N); 5962 ierr = MatPreallocated(A);CHKERRQ(ierr); 5963 ierr = PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 5964 ierr = (*A->ops->ptapsymbolic)(A,P,fill,C);CHKERRQ(ierr); 5965 ierr = PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 5966 5967 ierr = MatSetBlockSize(*C,A->bs);CHKERRQ(ierr); 5968 5969 PetscFunctionReturn(0); 5970 } 5971 5972 #undef __FUNCT__ 5973 #define __FUNCT__ "MatMatMult" 5974 /*@ 5975 MatMatMult - Performs Matrix-Matrix Multiplication C=A*B. 5976 5977 Collective on Mat 5978 5979 Input Parameters: 5980 + A - the left matrix 5981 . B - the right matrix 5982 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5983 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 5984 5985 Output Parameters: 5986 . C - the product matrix 5987 5988 Notes: 5989 C will be created and must be destroyed by the user with MatDestroy(). 5990 5991 This routine is currently only implemented for pairs of AIJ matrices and classes 5992 which inherit from AIJ. C will be of type MATAIJ. 5993 5994 Level: intermediate 5995 5996 .seealso: MatMatMultSymbolic(),MatMatMultNumeric() 5997 @*/ 5998 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 5999 { 6000 PetscErrorCode ierr; 6001 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6002 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6003 6004 PetscFunctionBegin; 6005 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6006 PetscValidType(A,1); 6007 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6008 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6009 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6010 PetscValidType(B,2); 6011 MatPreallocated(B); 6012 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6013 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6014 PetscValidPointer(C,3); 6015 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6016 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill); 6017 ierr = MatPreallocated(A);CHKERRQ(ierr); 6018 6019 /* For now, we do not dispatch based on the type of A and B */ 6020 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6021 fA = A->ops->matmult; 6022 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for A of type %s",A->type_name); 6023 fB = B->ops->matmult; 6024 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",B->type_name); 6025 if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMult requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6026 6027 ierr = PetscLogEventBegin(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6028 ierr = (*A->ops->matmult)(A,B,scall,fill,C);CHKERRQ(ierr); 6029 ierr = PetscLogEventEnd(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 6030 6031 PetscFunctionReturn(0); 6032 } 6033 6034 #undef __FUNCT__ 6035 #define __FUNCT__ "MatMatMultSymbolic" 6036 /*@ 6037 MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure 6038 of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric(). 6039 6040 Collective on Mat 6041 6042 Input Parameters: 6043 + A - the left matrix 6044 . B - the right matrix 6045 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6046 6047 Output Parameters: 6048 . C - the matrix containing the ij structure of product matrix 6049 6050 Notes: 6051 C will be created as a MATSEQAIJ matrix and must be destroyed by the user with MatDestroy(). 6052 6053 This routine is currently only implemented for SeqAIJ matrices and classes which inherit from SeqAIJ. 6054 6055 Level: intermediate 6056 6057 .seealso: MatMatMult(),MatMatMultNumeric() 6058 @*/ 6059 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C) 6060 { 6061 PetscErrorCode ierr; 6062 PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *); 6063 PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *); 6064 6065 PetscFunctionBegin; 6066 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6067 PetscValidType(A,1); 6068 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6069 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6070 6071 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6072 PetscValidType(B,2); 6073 MatPreallocated(B); 6074 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6075 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6076 PetscValidPointer(C,3); 6077 6078 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6079 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill); 6080 ierr = MatPreallocated(A);CHKERRQ(ierr); 6081 6082 /* For now, we do not dispatch based on the type of A and P */ 6083 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6084 Asymbolic = A->ops->matmultsymbolic; 6085 if (!Asymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for A of type %s",A->type_name); 6086 Bsymbolic = B->ops->matmultsymbolic; 6087 if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",B->type_name); 6088 if (Bsymbolic!=Asymbolic) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultSymbolic requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6089 6090 ierr = PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6091 ierr = (*Asymbolic)(A,B,fill,C);CHKERRQ(ierr); 6092 ierr = PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 6093 6094 PetscFunctionReturn(0); 6095 } 6096 6097 #undef __FUNCT__ 6098 #define __FUNCT__ "MatMatMultNumeric" 6099 /*@ 6100 MatMatMultNumeric - Performs the numeric matrix-matrix product. 6101 Call this routine after first calling MatMatMultSymbolic(). 6102 6103 Collective on Mat 6104 6105 Input Parameters: 6106 + A - the left matrix 6107 - B - the right matrix 6108 6109 Output Parameters: 6110 . C - the product matrix, whose ij structure was defined from MatMatMultSymbolic(). 6111 6112 Notes: 6113 C must have been created with MatMatMultSymbolic. 6114 6115 This routine is currently only implemented for SeqAIJ type matrices. 6116 6117 Level: intermediate 6118 6119 .seealso: MatMatMult(),MatMatMultSymbolic() 6120 @*/ 6121 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C) 6122 { 6123 PetscErrorCode ierr; 6124 PetscErrorCode (*Anumeric)(Mat,Mat,Mat); 6125 PetscErrorCode (*Bnumeric)(Mat,Mat,Mat); 6126 6127 PetscFunctionBegin; 6128 6129 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6130 PetscValidType(A,1); 6131 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6132 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6133 6134 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6135 PetscValidType(B,2); 6136 MatPreallocated(B); 6137 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6138 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6139 6140 PetscValidHeaderSpecific(C,MAT_COOKIE,3); 6141 PetscValidType(C,3); 6142 MatPreallocated(C); 6143 if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6144 if (C->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6145 6146 if (B->N!=C->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->N,C->N); 6147 if (B->M!=A->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->N); 6148 if (A->M!=C->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->M,C->M); 6149 ierr = MatPreallocated(A);CHKERRQ(ierr); 6150 6151 /* For now, we do not dispatch based on the type of A and B */ 6152 /* When implementations like _SeqAIJ_MAIJ exist, attack the multiple dispatch problem. */ 6153 Anumeric = A->ops->matmultnumeric; 6154 if (!Anumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for A of type %s",A->type_name); 6155 Bnumeric = B->ops->matmultnumeric; 6156 if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",B->type_name); 6157 if (Bnumeric!=Anumeric) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6158 6159 ierr = PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6160 ierr = (*Anumeric)(A,B,C);CHKERRQ(ierr); 6161 ierr = PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 6162 6163 PetscFunctionReturn(0); 6164 } 6165 6166 #undef __FUNCT__ 6167 #define __FUNCT__ "MatMatMultTranspose" 6168 /*@ 6169 MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B. 6170 6171 Collective on Mat 6172 6173 Input Parameters: 6174 + A - the left matrix 6175 . B - the right matrix 6176 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6177 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)) 6178 6179 Output Parameters: 6180 . C - the product matrix 6181 6182 Notes: 6183 C will be created and must be destroyed by the user with MatDestroy(). 6184 6185 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 6186 which inherit from SeqAIJ. C will be of type MATSEQAIJ. 6187 6188 Level: intermediate 6189 6190 .seealso: MatMatMultTransposeSymbolic(),MatMatMultTransposeNumeric() 6191 @*/ 6192 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 6193 { 6194 PetscErrorCode ierr; 6195 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 6196 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 6197 6198 PetscFunctionBegin; 6199 PetscValidHeaderSpecific(A,MAT_COOKIE,1); 6200 PetscValidType(A,1); 6201 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6202 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6203 PetscValidHeaderSpecific(B,MAT_COOKIE,2); 6204 PetscValidType(B,2); 6205 MatPreallocated(B); 6206 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6207 if (B->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6208 PetscValidPointer(C,3); 6209 if (B->M!=A->M) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->M,A->M); 6210 if (fill <=0.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"fill=%g must be > 0.0",fill); 6211 ierr = MatPreallocated(A);CHKERRQ(ierr); 6212 6213 fA = A->ops->matmulttranspose; 6214 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",A->type_name); 6215 fB = B->ops->matmulttranspose; 6216 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",B->type_name); 6217 if (fB!=fA) SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultTranspose requires A, %s, to be compatible with B, %s",A->type_name,B->type_name); 6218 6219 ierr = PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6220 ierr = (*A->ops->matmulttranspose)(A,B,scall,fill,C);CHKERRQ(ierr); 6221 ierr = PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 6222 6223 PetscFunctionReturn(0); 6224 } 6225