1 /*$Id: matrix.c,v 1.384 2000/11/07 16:18:58 bsmith Exp bsmith $*/ 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 "src/vec/vecimpl.h" 9 10 #undef __FUNC__ 11 #define __FUNC__ /*<a name=""></a>*/"MatGetRow" 12 /*@C 13 MatGetRow - Gets a row of a matrix. You MUST call MatRestoreRow() 14 for each row that you get to ensure that your application does 15 not bleed memory. 16 17 Not Collective 18 19 Input Parameters: 20 + mat - the matrix 21 - row - the row to get 22 23 Output Parameters: 24 + ncols - the number of nonzeros in the row 25 . cols - if not NULL, the column numbers 26 - vals - if not NULL, the values 27 28 Notes: 29 This routine is provided for people who need to have direct access 30 to the structure of a matrix. We hope that we provide enough 31 high-level matrix routines that few users will need it. 32 33 MatGetRow() always returns 0-based column indices, regardless of 34 whether the internal representation is 0-based (default) or 1-based. 35 36 For better efficiency, set cols and/or vals to PETSC_NULL if you do 37 not wish to extract these quantities. 38 39 The user can only examine the values extracted with MatGetRow(); 40 the values cannot be altered. To change the matrix entries, one 41 must use MatSetValues(). 42 43 You can only have one call to MatGetRow() outstanding for a particular 44 matrix at a time, per processor. MatGetRow() can only obtained rows 45 associated with the given processor, it cannot get rows from the 46 other processors; for that we suggest using MatGetSubMatrices(), then 47 MatGetRow() on the submatrix. The row indix passed to MatGetRows() 48 is in the global number of rows. 49 50 Fortran Notes: 51 The calling sequence from Fortran is 52 .vb 53 MatGetRow(matrix,row,ncols,cols,values,ierr) 54 Mat matrix (input) 55 integer row (input) 56 integer ncols (output) 57 integer cols(maxcols) (output) 58 double precision (or double complex) values(maxcols) output 59 .ve 60 where maxcols >= maximum nonzeros in any row of the matrix. 61 62 Caution: 63 Do not try to change the contents of the output arrays (cols and vals). 64 In some cases, this may corrupt the matrix. 65 66 Level: advanced 67 68 Concepts: matrices^row access 69 70 .seealso: MatRestoreRow(), MatSetValues(), MatGetValues(), MatGetSubmatrices(), MatGetDiagonal() 71 @*/ 72 int MatGetRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals) 73 { 74 int ierr; 75 76 PetscFunctionBegin; 77 PetscValidHeaderSpecific(mat,MAT_COOKIE); 78 PetscValidIntPointer(ncols); 79 PetscValidType(mat); 80 MatPreallocated(mat); 81 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 82 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 83 if (!mat->ops->getrow) SETERRQ(PETSC_ERR_SUP,""); 84 ierr = PLogEventBegin(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 85 ierr = (*mat->ops->getrow)(mat,row,ncols,cols,vals);CHKERRQ(ierr); 86 ierr = PLogEventEnd(MAT_GetRow,mat,0,0,0);CHKERRQ(ierr); 87 PetscFunctionReturn(0); 88 } 89 90 #undef __FUNC__ 91 #define __FUNC__ /*<a name=""></a>*/"MatRestoreRow" 92 /*@C 93 MatRestoreRow - Frees any temporary space allocated by MatGetRow(). 94 95 Not Collective 96 97 Input Parameters: 98 + mat - the matrix 99 . row - the row to get 100 . ncols, cols - the number of nonzeros and their columns 101 - vals - if nonzero the column values 102 103 Notes: 104 This routine should be called after you have finished examining the entries. 105 106 Fortran Notes: 107 The calling sequence from Fortran is 108 .vb 109 MatRestoreRow(matrix,row,ncols,cols,values,ierr) 110 Mat matrix (input) 111 integer row (input) 112 integer ncols (output) 113 integer cols(maxcols) (output) 114 double precision (or double complex) values(maxcols) output 115 .ve 116 Where maxcols >= maximum nonzeros in any row of the matrix. 117 118 In Fortran MatRestoreRow() MUST be called after MatGetRow() 119 before another call to MatGetRow() can be made. 120 121 Level: advanced 122 123 .seealso: MatGetRow() 124 @*/ 125 int MatRestoreRow(Mat mat,int row,int *ncols,int **cols,Scalar **vals) 126 { 127 int ierr; 128 129 PetscFunctionBegin; 130 PetscValidHeaderSpecific(mat,MAT_COOKIE); 131 PetscValidIntPointer(ncols); 132 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 133 if (!mat->ops->restorerow) PetscFunctionReturn(0); 134 ierr = (*mat->ops->restorerow)(mat,row,ncols,cols,vals);CHKERRQ(ierr); 135 PetscFunctionReturn(0); 136 } 137 138 #undef __FUNC__ 139 #define __FUNC__ /*<a name=""></a>*/"MatView" 140 /*@C 141 MatView - Visualizes a matrix object. 142 143 Collective on Mat 144 145 Input Parameters: 146 + mat - the matrix 147 - ptr - visualization context 148 149 Notes: 150 The available visualization contexts include 151 + VIEWER_STDOUT_SELF - standard output (default) 152 . VIEWER_STDOUT_WORLD - synchronized standard 153 output where only the first processor opens 154 the file. All other processors send their 155 data to the first processor to print. 156 - VIEWER_DRAW_WORLD - graphical display of nonzero structure 157 158 The user can open alternative visualization contexts with 159 + ViewerASCIIOpen() - Outputs matrix to a specified file 160 . ViewerBinaryOpen() - Outputs matrix in binary to a 161 specified file; corresponding input uses MatLoad() 162 . ViewerDrawOpen() - Outputs nonzero matrix structure to 163 an X window display 164 - ViewerSocketOpen() - Outputs matrix to Socket viewer. 165 Currently only the sequential dense and AIJ 166 matrix types support the Socket viewer. 167 168 The user can call ViewerSetFormat() to specify the output 169 format of ASCII printed objects (when using VIEWER_STDOUT_SELF, 170 VIEWER_STDOUT_WORLD and ViewerASCIIOpen). Available formats include 171 + VIEWER_FORMAT_ASCII_DEFAULT - default, prints matrix contents 172 . VIEWER_FORMAT_ASCII_MATLAB - prints matrix contents in Matlab format 173 . VIEWER_FORMAT_ASCII_DENSE - prints entire matrix including zeros 174 . VIEWER_FORMAT_ASCII_COMMON - prints matrix contents, using a sparse 175 format common among all matrix types 176 . VIEWER_FORMAT_ASCII_IMPL - prints matrix contents, using an implementation-specific 177 format (which is in many cases the same as the default) 178 . VIEWER_FORMAT_ASCII_INFO - prints basic information about the matrix 179 size and structure (not the matrix entries) 180 - VIEWER_FORMAT_ASCII_INFO_LONG - prints more detailed information about 181 the matrix structure 182 183 Level: beginner 184 185 Concepts: matrices^viewing 186 Concepts: matrices^plotting 187 Concepts: matrices^printing 188 189 .seealso: ViewerSetFormat(), ViewerASCIIOpen(), ViewerDrawOpen(), 190 ViewerSocketOpen(), ViewerBinaryOpen(), MatLoad() 191 @*/ 192 int MatView(Mat mat,Viewer viewer) 193 { 194 int format,ierr,rows,cols; 195 PetscTruth isascii; 196 char *cstr; 197 198 PetscFunctionBegin; 199 PetscValidHeaderSpecific(mat,MAT_COOKIE); 200 PetscValidType(mat); 201 MatPreallocated(mat); 202 if (!viewer) viewer = VIEWER_STDOUT_(mat->comm); 203 PetscValidHeaderSpecific(viewer,VIEWER_COOKIE); 204 PetscCheckSameComm(mat,viewer); 205 if (!mat->assembled) SETERRQ(1,"Must call MatAssemblyBegin/End() before viewing matrix"); 206 207 ierr = PetscTypeCompare((PetscObject)viewer,ASCII_VIEWER,&isascii);CHKERRQ(ierr); 208 if (isascii) { 209 ierr = ViewerGetFormat(viewer,&format);CHKERRQ(ierr); 210 if (format == VIEWER_FORMAT_ASCII_INFO || format == VIEWER_FORMAT_ASCII_INFO_LONG) { 211 ierr = ViewerASCIIPrintf(viewer,"Matrix Object:\n");CHKERRQ(ierr); 212 ierr = ViewerASCIIPushTab(viewer);CHKERRQ(ierr); 213 ierr = MatGetType(mat,&cstr);CHKERRQ(ierr); 214 ierr = MatGetSize(mat,&rows,&cols);CHKERRQ(ierr); 215 ierr = ViewerASCIIPrintf(viewer,"type=%s, rows=%d, cols=%d\n",cstr,rows,cols);CHKERRQ(ierr); 216 if (mat->ops->getinfo) { 217 MatInfo info; 218 ierr = MatGetInfo(mat,MAT_GLOBAL_SUM,&info);CHKERRQ(ierr); 219 ierr = ViewerASCIIPrintf(viewer,"total: nonzeros=%d, allocated nonzeros=%d\n", 220 (int)info.nz_used,(int)info.nz_allocated);CHKERRQ(ierr); 221 } 222 } 223 } 224 if (mat->ops->view) { 225 ierr = ViewerASCIIPushTab(viewer);CHKERRQ(ierr); 226 ierr = (*mat->ops->view)(mat,viewer);CHKERRQ(ierr); 227 ierr = ViewerASCIIPopTab(viewer);CHKERRQ(ierr); 228 } else if (!isascii) { 229 SETERRQ1(1,"Viewer type %s not supported",((PetscObject)viewer)->type_name); 230 } 231 if (isascii) { 232 ierr = ViewerGetFormat(viewer,&format);CHKERRQ(ierr); 233 if (format == VIEWER_FORMAT_ASCII_INFO || format == VIEWER_FORMAT_ASCII_INFO_LONG) { 234 ierr = ViewerASCIIPopTab(viewer);CHKERRQ(ierr); 235 } 236 } 237 PetscFunctionReturn(0); 238 } 239 240 #undef __FUNC__ 241 #define __FUNC__ /*<a name=""></a>*/"MatScaleSystem" 242 /*@C 243 MatScaleSystem - Scale a vector solution and right hand side to 244 match the scaling of a scaled matrix. 245 246 Collective on Mat 247 248 Input Parameter: 249 + mat - the matrix 250 . x - solution vector (or PETSC_NULL) 251 + b - right hand side vector (or PETSC_NULL) 252 253 254 Notes: 255 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 256 internally scaled, so this does nothing. For MPIROWBS it 257 permutes and diagonally scales. 258 259 The SLES methods automatically call this routine when required 260 (via PCPreSolve()) so it is rarely used directly. 261 262 Level: Developer 263 264 Concepts: matrices^scaling 265 266 .seealso: MatUseScaledForm(), MatUnScaleSystem() 267 @*/ 268 int MatScaleSystem(Mat mat,Vec x,Vec b) 269 { 270 int ierr; 271 272 PetscFunctionBegin; 273 PetscValidHeaderSpecific(mat,MAT_COOKIE); 274 PetscValidType(mat); 275 MatPreallocated(mat); 276 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE);PetscCheckSameComm(mat,x);} 277 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE);PetscCheckSameComm(mat,b);} 278 279 if (mat->ops->scalesystem) { 280 ierr = (*mat->ops->scalesystem)(mat,x,b);CHKERRQ(ierr); 281 } 282 PetscFunctionReturn(0); 283 } 284 285 #undef __FUNC__ 286 #define __FUNC__ /*<a name=""></a>*/"MatUnScaleSystem" 287 /*@C 288 MatUnScaleSystem - Unscales a vector solution and right hand side to 289 match the original scaling of a scaled matrix. 290 291 Collective on Mat 292 293 Input Parameter: 294 + mat - the matrix 295 . x - solution vector (or PETSC_NULL) 296 + b - right hand side vector (or PETSC_NULL) 297 298 299 Notes: 300 For AIJ, BAIJ, and BDiag matrix formats, the matrices are not 301 internally scaled, so this does nothing. For MPIROWBS it 302 permutes and diagonally scales. 303 304 The SLES methods automatically call this routine when required 305 (via PCPreSolve()) so it is rarely used directly. 306 307 Level: Developer 308 309 .seealso: MatUseScaledForm(), MatScaleSystem() 310 @*/ 311 int MatUnScaleSystem(Mat mat,Vec x,Vec b) 312 { 313 int ierr; 314 315 PetscFunctionBegin; 316 PetscValidHeaderSpecific(mat,MAT_COOKIE); 317 PetscValidType(mat); 318 MatPreallocated(mat); 319 if (x) {PetscValidHeaderSpecific(x,VEC_COOKIE);PetscCheckSameComm(mat,x);} 320 if (b) {PetscValidHeaderSpecific(b,VEC_COOKIE);PetscCheckSameComm(mat,b);} 321 if (mat->ops->unscalesystem) { 322 ierr = (*mat->ops->unscalesystem)(mat,x,b);CHKERRQ(ierr); 323 } 324 PetscFunctionReturn(0); 325 } 326 327 #undef __FUNC__ 328 #define __FUNC__ /*<a name=""></a>*/"MatUseScaledForm" 329 /*@C 330 MatUseScaledForm - For matrix storage formats that scale the 331 matrix (for example MPIRowBS matrices are diagonally scaled on 332 assembly) indicates matrix operations (MatMult() etc) are 333 applied using the scaled matrix. 334 335 Collective on Mat 336 337 Input Parameter: 338 + mat - the matrix 339 - scaled - PETSC_TRUE for applying the scaled, PETSC_FALSE for 340 applying the original matrix 341 342 Notes: 343 For scaled matrix formats, applying the original, unscaled matrix 344 will be slightly more expensive 345 346 Level: Developer 347 348 .seealso: MatScaleSystem(), MatUnScaleSystem() 349 @*/ 350 int MatUseScaledForm(Mat mat,PetscTruth scaled) 351 { 352 int ierr; 353 354 PetscFunctionBegin; 355 PetscValidHeaderSpecific(mat,MAT_COOKIE); 356 PetscValidType(mat); 357 MatPreallocated(mat); 358 if (mat->ops->usescaledform) { 359 ierr = (*mat->ops->usescaledform)(mat,scaled);CHKERRQ(ierr); 360 } 361 PetscFunctionReturn(0); 362 } 363 364 #undef __FUNC__ 365 #define __FUNC__ /*<a name=""></a>*/"MatDestroy" 366 /*@C 367 MatDestroy - Frees space taken by a matrix. 368 369 Collective on Mat 370 371 Input Parameter: 372 . A - the matrix 373 374 Level: beginner 375 376 @*/ 377 int MatDestroy(Mat A) 378 { 379 int ierr; 380 381 PetscFunctionBegin; 382 PetscValidHeaderSpecific(A,MAT_COOKIE); 383 PetscValidType(A); 384 MatPreallocated(A); 385 if (--A->refct > 0) PetscFunctionReturn(0); 386 387 /* if memory was published with AMS then destroy it */ 388 ierr = PetscObjectDepublish(A);CHKERRQ(ierr); 389 if (A->mapping) { 390 ierr = ISLocalToGlobalMappingDestroy(A->mapping);CHKERRQ(ierr); 391 } 392 if (A->bmapping) { 393 ierr = ISLocalToGlobalMappingDestroy(A->bmapping);CHKERRQ(ierr); 394 } 395 if (A->rmap) { 396 ierr = MapDestroy(A->rmap);CHKERRQ(ierr); 397 } 398 if (A->cmap) { 399 ierr = MapDestroy(A->cmap);CHKERRQ(ierr); 400 } 401 402 ierr = (*A->ops->destroy)(A);CHKERRQ(ierr); 403 PLogObjectDestroy(A); 404 PetscHeaderDestroy(A); 405 PetscFunctionReturn(0); 406 } 407 408 #undef __FUNC__ 409 #define __FUNC__ /*<a name=""></a>*/"MatValid" 410 /*@ 411 MatValid - Checks whether a matrix object is valid. 412 413 Collective on Mat 414 415 Input Parameter: 416 . m - the matrix to check 417 418 Output Parameter: 419 flg - flag indicating matrix status, either 420 PETSC_TRUE if matrix is valid, or PETSC_FALSE otherwise. 421 422 Level: developer 423 424 Concepts: matrices^validity 425 @*/ 426 int MatValid(Mat m,PetscTruth *flg) 427 { 428 PetscFunctionBegin; 429 PetscValidIntPointer(flg); 430 if (!m) *flg = PETSC_FALSE; 431 else if (m->cookie != MAT_COOKIE) *flg = PETSC_FALSE; 432 else *flg = PETSC_TRUE; 433 PetscFunctionReturn(0); 434 } 435 436 #undef __FUNC__ 437 #define __FUNC__ /*<a name=""></a>*/"MatSetValues" 438 /*@ 439 MatSetValues - Inserts or adds a block of values into a matrix. 440 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 441 MUST be called after all calls to MatSetValues() have been completed. 442 443 Not Collective 444 445 Input Parameters: 446 + mat - the matrix 447 . v - a logically two-dimensional array of values 448 . m, idxm - the number of rows and their global indices 449 . n, idxn - the number of columns and their global indices 450 - addv - either ADD_VALUES or INSERT_VALUES, where 451 ADD_VALUES adds values to any existing entries, and 452 INSERT_VALUES replaces existing entries with new values 453 454 Notes: 455 By default the values, v, are row-oriented and unsorted. 456 See MatSetOption() for other options. 457 458 Calls to MatSetValues() with the INSERT_VALUES and ADD_VALUES 459 options cannot be mixed without intervening calls to the assembly 460 routines. 461 462 MatSetValues() uses 0-based row and column numbers in Fortran 463 as well as in C. 464 465 Negative indices may be passed in idxm and idxn, these rows and columns are 466 simply ignored. This allows easily inserting element stiffness matrices 467 with homogeneous Dirchlet boundary conditions that you don't want represented 468 in the matrix. 469 470 Efficiency Alert: 471 The routine MatSetValuesBlocked() may offer much better efficiency 472 for users of block sparse formats (MATSEQBAIJ and MATMPIBAIJ). 473 474 Level: beginner 475 476 Concepts: matrices^putting entries in 477 478 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal() 479 @*/ 480 int MatSetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv) 481 { 482 int ierr; 483 484 PetscFunctionBegin; 485 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 486 PetscValidHeaderSpecific(mat,MAT_COOKIE); 487 PetscValidType(mat); 488 MatPreallocated(mat); 489 PetscValidIntPointer(idxm); 490 PetscValidIntPointer(idxn); 491 PetscValidScalarPointer(v); 492 if (mat->insertmode == NOT_SET_VALUES) { 493 mat->insertmode = addv; 494 } 495 #if defined(PETSC_USE_BOPT_g) 496 else if (mat->insertmode != addv) { 497 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 498 } 499 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 500 #endif 501 502 if (mat->assembled) { 503 mat->was_assembled = PETSC_TRUE; 504 mat->assembled = PETSC_FALSE; 505 } 506 ierr = PLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 507 if (!mat->ops->setvalues) SETERRQ(PETSC_ERR_SUP,"Not supported for this matrix type"); 508 ierr = (*mat->ops->setvalues)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 509 ierr = PLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 510 PetscFunctionReturn(0); 511 } 512 513 #undef __FUNC__ 514 #define __FUNC__ /*<a name=""></a>*/"MatSetValuesBlocked" 515 /*@ 516 MatSetValuesBlocked - Inserts or adds a block of values into a matrix. 517 518 Not Collective 519 520 Input Parameters: 521 + mat - the matrix 522 . v - a logically two-dimensional array of values 523 . m, idxm - the number of block rows and their global block indices 524 . n, idxn - the number of block columns and their global block indices 525 - addv - either ADD_VALUES or INSERT_VALUES, where 526 ADD_VALUES adds values to any existing entries, and 527 INSERT_VALUES replaces existing entries with new values 528 529 Notes: 530 By default the values, v, are row-oriented and unsorted. So the layout of 531 v is the same as for MatSetValues(). See MatSetOption() for other options. 532 533 Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 534 options cannot be mixed without intervening calls to the assembly 535 routines. 536 537 MatSetValuesBlocked() uses 0-based row and column numbers in Fortran 538 as well as in C. 539 540 Negative indices may be passed in idxm and idxn, these rows and columns are 541 simply ignored. This allows easily inserting element stiffness matrices 542 with homogeneous Dirchlet boundary conditions that you don't want represented 543 in the matrix. 544 545 Each time an entry is set within a sparse matrix via MatSetValues(), 546 internal searching must be done to determine where to place the the 547 data in the matrix storage space. By instead inserting blocks of 548 entries via MatSetValuesBlocked(), the overhead of matrix assembly is 549 reduced. 550 551 Restrictions: 552 MatSetValuesBlocked() is currently supported only for the block AIJ 553 matrix format (MATSEQBAIJ and MATMPIBAIJ, which are created via 554 MatCreateSeqBAIJ() and MatCreateMPIBAIJ()). 555 556 Level: intermediate 557 558 Concepts: matrices^putting entries in blocked 559 560 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal() 561 @*/ 562 int MatSetValuesBlocked(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v,InsertMode addv) 563 { 564 int ierr; 565 566 PetscFunctionBegin; 567 if (!m || !n) PetscFunctionReturn(0); /* no values to insert */ 568 PetscValidHeaderSpecific(mat,MAT_COOKIE); 569 PetscValidType(mat); 570 MatPreallocated(mat); 571 PetscValidIntPointer(idxm); 572 PetscValidIntPointer(idxn); 573 PetscValidScalarPointer(v); 574 if (mat->insertmode == NOT_SET_VALUES) { 575 mat->insertmode = addv; 576 } 577 #if defined(PETSC_USE_BOPT_g) 578 else if (mat->insertmode != addv) { 579 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 580 } 581 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 582 #endif 583 584 if (mat->assembled) { 585 mat->was_assembled = PETSC_TRUE; 586 mat->assembled = PETSC_FALSE; 587 } 588 ierr = PLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 589 if (!mat->ops->setvaluesblocked) SETERRQ(PETSC_ERR_SUP,"Not supported for this matrix type"); 590 ierr = (*mat->ops->setvaluesblocked)(mat,m,idxm,n,idxn,v,addv);CHKERRQ(ierr); 591 ierr = PLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 592 PetscFunctionReturn(0); 593 } 594 595 /*MC 596 MatSetValue - Set a single entry into a matrix. 597 598 Synopsis: 599 void MatSetValue(Mat m,int row,int col,Scalar value,InsertMode mode); 600 601 Not collective 602 603 Input Parameters: 604 + m - the matrix 605 . row - the row location of the entry 606 . col - the column location of the entry 607 . value - the value to insert 608 - mode - either INSERT_VALUES or ADD_VALUES 609 610 Notes: 611 For efficiency one should use MatSetValues() and set several or many 612 values simultaneously if possible. 613 614 Note that VecSetValue() does NOT return an error code (since this 615 is checked internally). 616 617 Level: beginner 618 619 .seealso: MatSetValues() 620 M*/ 621 622 #undef __FUNC__ 623 #define __FUNC__ /*<a name=""></a>*/"MatGetValues" 624 /*@ 625 MatGetValues - Gets a block of values from a matrix. 626 627 Not Collective; currently only returns a local block 628 629 Input Parameters: 630 + mat - the matrix 631 . v - a logically two-dimensional array for storing the values 632 . m, idxm - the number of rows and their global indices 633 - n, idxn - the number of columns and their global indices 634 635 Notes: 636 The user must allocate space (m*n Scalars) for the values, v. 637 The values, v, are then returned in a row-oriented format, 638 analogous to that used by default in MatSetValues(). 639 640 MatGetValues() uses 0-based row and column numbers in 641 Fortran as well as in C. 642 643 MatGetValues() requires that the matrix has been assembled 644 with MatAssemblyBegin()/MatAssemblyEnd(). Thus, calls to 645 MatSetValues() and MatGetValues() CANNOT be made in succession 646 without intermediate matrix assembly. 647 648 Level: advanced 649 650 Concepts: matrices^accessing values 651 652 .seealso: MatGetRow(), MatGetSubmatrices(), MatSetValues() 653 @*/ 654 int MatGetValues(Mat mat,int m,int *idxm,int n,int *idxn,Scalar *v) 655 { 656 int ierr; 657 658 PetscFunctionBegin; 659 PetscValidHeaderSpecific(mat,MAT_COOKIE); 660 PetscValidType(mat); 661 MatPreallocated(mat); 662 PetscValidIntPointer(idxm); 663 PetscValidIntPointer(idxn); 664 PetscValidScalarPointer(v); 665 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 666 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 667 if (!mat->ops->getvalues) SETERRQ(PETSC_ERR_SUP,""); 668 669 ierr = PLogEventBegin(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 670 ierr = (*mat->ops->getvalues)(mat,m,idxm,n,idxn,v);CHKERRQ(ierr); 671 ierr = PLogEventEnd(MAT_GetValues,mat,0,0,0);CHKERRQ(ierr); 672 PetscFunctionReturn(0); 673 } 674 675 #undef __FUNC__ 676 #define __FUNC__ /*<a name=""></a>*/"MatSetLocalToGlobalMapping" 677 /*@ 678 MatSetLocalToGlobalMapping - Sets a local-to-global numbering for use by 679 the routine MatSetValuesLocal() to allow users to insert matrix entries 680 using a local (per-processor) numbering. 681 682 Not Collective 683 684 Input Parameters: 685 + x - the matrix 686 - mapping - mapping created with ISLocalToGlobalMappingCreate() 687 or ISLocalToGlobalMappingCreateIS() 688 689 Level: intermediate 690 691 Concepts: matrices^local to global mapping 692 Concepts: local to global mapping^for matrices 693 694 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesLocal() 695 @*/ 696 int MatSetLocalToGlobalMapping(Mat x,ISLocalToGlobalMapping mapping) 697 { 698 int ierr; 699 PetscFunctionBegin; 700 PetscValidHeaderSpecific(x,MAT_COOKIE); 701 PetscValidType(x); 702 MatPreallocated(x); 703 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE); 704 if (x->mapping) { 705 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 706 } 707 708 if (x->ops->setlocaltoglobalmapping) { 709 ierr = (*x->ops->setlocaltoglobalmapping)(x,mapping);CHKERRQ(ierr); 710 } else { 711 x->mapping = mapping; 712 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 713 } 714 PetscFunctionReturn(0); 715 } 716 717 #undef __FUNC__ 718 #define __FUNC__ /*<a name=""></a>*/"MatSetLocalToGlobalMappingBlock" 719 /*@ 720 MatSetLocalToGlobalMappingBlock - Sets a local-to-global numbering for use 721 by the routine MatSetValuesBlockedLocal() to allow users to insert matrix 722 entries using a local (per-processor) numbering. 723 724 Not Collective 725 726 Input Parameters: 727 + x - the matrix 728 - mapping - mapping created with ISLocalToGlobalMappingCreate() or 729 ISLocalToGlobalMappingCreateIS() 730 731 Level: intermediate 732 733 Concepts: matrices^local to global mapping blocked 734 Concepts: local to global mapping^for matrices, blocked 735 736 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetValuesBlockedLocal(), 737 MatSetValuesBlocked(), MatSetValuesLocal() 738 @*/ 739 int MatSetLocalToGlobalMappingBlock(Mat x,ISLocalToGlobalMapping mapping) 740 { 741 int ierr; 742 PetscFunctionBegin; 743 PetscValidHeaderSpecific(x,MAT_COOKIE); 744 PetscValidType(x); 745 MatPreallocated(x); 746 PetscValidHeaderSpecific(mapping,IS_LTOGM_COOKIE); 747 if (x->bmapping) { 748 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for matrix"); 749 } 750 751 x->bmapping = mapping; 752 ierr = PetscObjectReference((PetscObject)mapping);CHKERRQ(ierr); 753 PetscFunctionReturn(0); 754 } 755 756 #undef __FUNC__ 757 #define __FUNC__ /*<a name=""></a>*/"MatSetValuesLocal" 758 /*@ 759 MatSetValuesLocal - Inserts or adds values into certain locations of a matrix, 760 using a local ordering of the nodes. 761 762 Not Collective 763 764 Input Parameters: 765 + x - the matrix 766 . nrow, irow - number of rows and their local indices 767 . ncol, icol - number of columns and their local indices 768 . y - a logically two-dimensional array of values 769 - addv - either INSERT_VALUES or ADD_VALUES, where 770 ADD_VALUES adds values to any existing entries, and 771 INSERT_VALUES replaces existing entries with new values 772 773 Notes: 774 Before calling MatSetValuesLocal(), the user must first set the 775 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 776 777 Calls to MatSetValuesLocal() with the INSERT_VALUES and ADD_VALUES 778 options cannot be mixed without intervening calls to the assembly 779 routines. 780 781 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 782 MUST be called after all calls to MatSetValuesLocal() have been completed. 783 784 Level: intermediate 785 786 Concepts: matrices^putting entries in with local numbering 787 788 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValues(), MatSetLocalToGlobalMapping(), 789 MatSetValueLocal() 790 @*/ 791 int MatSetValuesLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv) 792 { 793 int ierr,irowm[2048],icolm[2048]; 794 795 PetscFunctionBegin; 796 PetscValidHeaderSpecific(mat,MAT_COOKIE); 797 PetscValidType(mat); 798 MatPreallocated(mat); 799 PetscValidIntPointer(irow); 800 PetscValidIntPointer(icol); 801 PetscValidScalarPointer(y); 802 803 if (mat->insertmode == NOT_SET_VALUES) { 804 mat->insertmode = addv; 805 } 806 #if defined(PETSC_USE_BOPT_g) 807 else if (mat->insertmode != addv) { 808 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 809 } 810 if (!mat->ops->setvalueslocal && (nrow > 2048 || ncol > 2048)) { 811 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol); 812 } 813 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 814 #endif 815 816 if (mat->assembled) { 817 mat->was_assembled = PETSC_TRUE; 818 mat->assembled = PETSC_FALSE; 819 } 820 ierr = PLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 821 if (!mat->ops->setvalueslocal) { 822 ierr = ISLocalToGlobalMappingApply(mat->mapping,nrow,irow,irowm);CHKERRQ(ierr); 823 ierr = ISLocalToGlobalMappingApply(mat->mapping,ncol,icol,icolm);CHKERRQ(ierr); 824 ierr = (*mat->ops->setvalues)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 825 } else { 826 ierr = (*mat->ops->setvalueslocal)(mat,nrow,irow,ncol,icol,y,addv);CHKERRQ(ierr); 827 } 828 ierr = PLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 829 PetscFunctionReturn(0); 830 } 831 832 #undef __FUNC__ 833 #define __FUNC__ /*<a name=""></a>*/"MatSetValuesBlockedLocal" 834 /*@ 835 MatSetValuesBlockedLocal - Inserts or adds values into certain locations of a matrix, 836 using a local ordering of the nodes a block at a time. 837 838 Not Collective 839 840 Input Parameters: 841 + x - the matrix 842 . nrow, irow - number of rows and their local indices 843 . ncol, icol - number of columns and their local indices 844 . y - a logically two-dimensional array of values 845 - addv - either INSERT_VALUES or ADD_VALUES, where 846 ADD_VALUES adds values to any existing entries, and 847 INSERT_VALUES replaces existing entries with new values 848 849 Notes: 850 Before calling MatSetValuesBlockedLocal(), the user must first set the 851 local-to-global mapping by calling MatSetLocalToGlobalMappingBlock(), 852 where the mapping MUST be set for matrix blocks, not for matrix elements. 853 854 Calls to MatSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 855 options cannot be mixed without intervening calls to the assembly 856 routines. 857 858 These values may be cached, so MatAssemblyBegin() and MatAssemblyEnd() 859 MUST be called after all calls to MatSetValuesBlockedLocal() have been completed. 860 861 Level: intermediate 862 863 Concepts: matrices^putting blocked values in with local numbering 864 865 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesLocal(), MatSetLocalToGlobalMappingBlock(), MatSetValuesBlocked() 866 @*/ 867 int MatSetValuesBlockedLocal(Mat mat,int nrow,int *irow,int ncol,int *icol,Scalar *y,InsertMode addv) 868 { 869 int ierr,irowm[2048],icolm[2048]; 870 871 PetscFunctionBegin; 872 PetscValidHeaderSpecific(mat,MAT_COOKIE); 873 PetscValidType(mat); 874 MatPreallocated(mat); 875 PetscValidIntPointer(irow); 876 PetscValidIntPointer(icol); 877 PetscValidScalarPointer(y); 878 if (mat->insertmode == NOT_SET_VALUES) { 879 mat->insertmode = addv; 880 } 881 #if defined(PETSC_USE_BOPT_g) 882 else if (mat->insertmode != addv) { 883 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot mix add values and insert values"); 884 } 885 if (!mat->bmapping) { 886 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with MatSetLocalToGlobalMappingBlock()"); 887 } 888 if (nrow > 2048 || ncol > 2048) { 889 SETERRQ2(PETSC_ERR_SUP,"Number column/row indices must be <= 2048: are %d %d",nrow,ncol); 890 } 891 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 892 #endif 893 894 if (mat->assembled) { 895 mat->was_assembled = PETSC_TRUE; 896 mat->assembled = PETSC_FALSE; 897 } 898 ierr = PLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 899 ierr = ISLocalToGlobalMappingApply(mat->bmapping,nrow,irow,irowm);CHKERRQ(ierr); 900 ierr = ISLocalToGlobalMappingApply(mat->bmapping,ncol,icol,icolm);CHKERRQ(ierr); 901 ierr = (*mat->ops->setvaluesblocked)(mat,nrow,irowm,ncol,icolm,y,addv);CHKERRQ(ierr); 902 ierr = PLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 903 PetscFunctionReturn(0); 904 } 905 906 /* --------------------------------------------------------*/ 907 #undef __FUNC__ 908 #define __FUNC__ /*<a name=""></a>*/"MatMult" 909 /*@ 910 MatMult - Computes the matrix-vector product, y = Ax. 911 912 Collective on Mat and Vec 913 914 Input Parameters: 915 + mat - the matrix 916 - x - the vector to be multilplied 917 918 Output Parameters: 919 . y - the result 920 921 Notes: 922 The vectors x and y cannot be the same. I.e., one cannot 923 call MatMult(A,y,y). 924 925 Level: beginner 926 927 Concepts: matrix-vector product 928 929 .seealso: MatMultTranspose(), MatMultAdd(), MatMultTransposeAdd() 930 @*/ 931 int MatMult(Mat mat,Vec x,Vec y) 932 { 933 int ierr; 934 935 PetscFunctionBegin; 936 PetscValidHeaderSpecific(mat,MAT_COOKIE); 937 PetscValidType(mat); 938 MatPreallocated(mat); 939 PetscValidHeaderSpecific(x,VEC_COOKIE); 940 PetscValidHeaderSpecific(y,VEC_COOKIE); 941 942 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 943 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 944 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 945 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 946 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N); 947 if (mat->m != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: local dim %d %d",mat->m,y->n); 948 949 if (mat->nullsp) { 950 ierr = MatNullSpaceRemove(mat->nullsp,x,&x);CHKERRQ(ierr); 951 } 952 953 ierr = PLogEventBegin(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 954 ierr = (*mat->ops->mult)(mat,x,y);CHKERRQ(ierr); 955 ierr = PLogEventEnd(MAT_Mult,mat,x,y,0);CHKERRQ(ierr); 956 957 if (mat->nullsp) { 958 ierr = MatNullSpaceRemove(mat->nullsp,y,PETSC_NULL);CHKERRQ(ierr); 959 } 960 PetscFunctionReturn(0); 961 } 962 963 #undef __FUNC__ 964 #define __FUNC__ /*<a name=""></a>*/"MatMultTranspose" 965 /*@ 966 MatMultTranspose - Computes matrix transpose times a vector. 967 968 Collective on Mat and Vec 969 970 Input Parameters: 971 + mat - the matrix 972 - x - the vector to be multilplied 973 974 Output Parameters: 975 . y - the result 976 977 Notes: 978 The vectors x and y cannot be the same. I.e., one cannot 979 call MatMultTranspose(A,y,y). 980 981 Level: beginner 982 983 Concepts: matrix vector product^transpose 984 985 .seealso: MatMult(), MatMultAdd(), MatMultTransposeAdd() 986 @*/ 987 int MatMultTranspose(Mat mat,Vec x,Vec y) 988 { 989 int ierr; 990 991 PetscFunctionBegin; 992 PetscValidHeaderSpecific(mat,MAT_COOKIE); 993 PetscValidType(mat); 994 MatPreallocated(mat); 995 PetscValidHeaderSpecific(x,VEC_COOKIE); 996 PetscValidHeaderSpecific(y,VEC_COOKIE); 997 998 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 999 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1000 if (x == y) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"x and y must be different vectors"); 1001 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N); 1002 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N); 1003 1004 ierr = PLogEventBegin(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1005 ierr = (*mat->ops->multtranspose)(mat,x,y);CHKERRQ(ierr); 1006 ierr = PLogEventEnd(MAT_MultTranspose,mat,x,y,0);CHKERRQ(ierr); 1007 PetscFunctionReturn(0); 1008 } 1009 1010 #undef __FUNC__ 1011 #define __FUNC__ /*<a name=""></a>*/"MatMultAdd" 1012 /*@ 1013 MatMultAdd - Computes v3 = v2 + A * v1. 1014 1015 Collective on Mat and Vec 1016 1017 Input Parameters: 1018 + mat - the matrix 1019 - v1, v2 - the vectors 1020 1021 Output Parameters: 1022 . v3 - the result 1023 1024 Notes: 1025 The vectors v1 and v3 cannot be the same. I.e., one cannot 1026 call MatMultAdd(A,v1,v2,v1). 1027 1028 Level: beginner 1029 1030 Concepts: matrix vector product^addition 1031 1032 .seealso: MatMultTranspose(), MatMult(), MatMultTransposeAdd() 1033 @*/ 1034 int MatMultAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1035 { 1036 int ierr; 1037 1038 PetscFunctionBegin; 1039 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1040 PetscValidType(mat); 1041 MatPreallocated(mat); 1042 PetscValidHeaderSpecific(v1,VEC_COOKIE); 1043 PetscValidHeaderSpecific(v2,VEC_COOKIE); 1044 PetscValidHeaderSpecific(v3,VEC_COOKIE); 1045 1046 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1047 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1048 if (mat->N != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->N,v1->N); 1049 if (mat->M != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->M,v2->N); 1050 if (mat->M != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->M,v3->N); 1051 if (mat->m != v3->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: local dim %d %d",mat->m,v3->n); 1052 if (mat->m != v2->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: local dim %d %d",mat->m,v2->n); 1053 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1054 1055 ierr = PLogEventBegin(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1056 ierr = (*mat->ops->multadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1057 ierr = PLogEventEnd(MAT_MultAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1058 PetscFunctionReturn(0); 1059 } 1060 1061 #undef __FUNC__ 1062 #define __FUNC__ /*<a name=""></a>*/"MatMultTransposeAdd" 1063 /*@ 1064 MatMultTransposeAdd - Computes v3 = v2 + A' * v1. 1065 1066 Collective on Mat and Vec 1067 1068 Input Parameters: 1069 + mat - the matrix 1070 - v1, v2 - the vectors 1071 1072 Output Parameters: 1073 . v3 - the result 1074 1075 Notes: 1076 The vectors v1 and v3 cannot be the same. I.e., one cannot 1077 call MatMultTransposeAdd(A,v1,v2,v1). 1078 1079 Level: beginner 1080 1081 Concepts: matrix vector product^transpose and addition 1082 1083 .seealso: MatMultTranspose(), MatMultAdd(), MatMult() 1084 @*/ 1085 int MatMultTransposeAdd(Mat mat,Vec v1,Vec v2,Vec v3) 1086 { 1087 int ierr; 1088 1089 PetscFunctionBegin; 1090 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1091 PetscValidType(mat); 1092 MatPreallocated(mat); 1093 PetscValidHeaderSpecific(v1,VEC_COOKIE); 1094 PetscValidHeaderSpecific(v2,VEC_COOKIE); 1095 PetscValidHeaderSpecific(v3,VEC_COOKIE); 1096 1097 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1098 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1099 if (!mat->ops->multtransposeadd) SETERRQ(PETSC_ERR_SUP,""); 1100 if (v1 == v3) SETERRQ(PETSC_ERR_ARG_IDN,"v1 and v3 must be different vectors"); 1101 if (mat->M != v1->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v1: global dim %d %d",mat->M,v1->N); 1102 if (mat->N != v2->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v2: global dim %d %d",mat->N,v2->N); 1103 if (mat->N != v3->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec v3: global dim %d %d",mat->N,v3->N); 1104 1105 ierr = PLogEventBegin(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1106 ierr = (*mat->ops->multtransposeadd)(mat,v1,v2,v3);CHKERRQ(ierr); 1107 ierr = PLogEventEnd(MAT_MultTransposeAdd,mat,v1,v2,v3);CHKERRQ(ierr); 1108 PetscFunctionReturn(0); 1109 } 1110 /* ------------------------------------------------------------*/ 1111 #undef __FUNC__ 1112 #define __FUNC__ /*<a name=""></a>*/"MatGetInfo" 1113 /*@C 1114 MatGetInfo - Returns information about matrix storage (number of 1115 nonzeros, memory, etc.). 1116 1117 Collective on Mat if MAT_GLOBAL_MAX or MAT_GLOBAL_SUM is used 1118 as the flag 1119 1120 Input Parameters: 1121 . mat - the matrix 1122 1123 Output Parameters: 1124 + flag - flag indicating the type of parameters to be returned 1125 (MAT_LOCAL - local matrix, MAT_GLOBAL_MAX - maximum over all processors, 1126 MAT_GLOBAL_SUM - sum over all processors) 1127 - info - matrix information context 1128 1129 Notes: 1130 The MatInfo context contains a variety of matrix data, including 1131 number of nonzeros allocated and used, number of mallocs during 1132 matrix assembly, etc. Additional information for factored matrices 1133 is provided (such as the fill ratio, number of mallocs during 1134 factorization, etc.). Much of this info is printed to STDOUT 1135 when using the runtime options 1136 $ -log_info -mat_view_info 1137 1138 Example for C/C++ Users: 1139 See the file ${PETSC_DIR}/include/petscmat.h for a complete list of 1140 data within the MatInfo context. For example, 1141 .vb 1142 MatInfo info; 1143 Mat A; 1144 double mal, nz_a, nz_u; 1145 1146 MatGetInfo(A,MAT_LOCAL,&info); 1147 mal = info.mallocs; 1148 nz_a = info.nz_allocated; 1149 .ve 1150 1151 Example for Fortran Users: 1152 Fortran users should declare info as a double precision 1153 array of dimension MAT_INFO_SIZE, and then extract the parameters 1154 of interest. See the file ${PETSC_DIR}/include/finclude/petscmat.h 1155 a complete list of parameter names. 1156 .vb 1157 double precision info(MAT_INFO_SIZE) 1158 double precision mal, nz_a 1159 Mat A 1160 integer ierr 1161 1162 call MatGetInfo(A,MAT_LOCAL,info,ierr) 1163 mal = info(MAT_INFO_MALLOCS) 1164 nz_a = info(MAT_INFO_NZ_ALLOCATED) 1165 .ve 1166 1167 Level: intermediate 1168 1169 Concepts: matrices^getting information on 1170 1171 @*/ 1172 int MatGetInfo(Mat mat,MatInfoType flag,MatInfo *info) 1173 { 1174 int ierr; 1175 1176 PetscFunctionBegin; 1177 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1178 PetscValidType(mat); 1179 MatPreallocated(mat); 1180 PetscValidPointer(info); 1181 if (!mat->ops->getinfo) SETERRQ(PETSC_ERR_SUP,""); 1182 ierr = (*mat->ops->getinfo)(mat,flag,info);CHKERRQ(ierr); 1183 PetscFunctionReturn(0); 1184 } 1185 1186 /* ----------------------------------------------------------*/ 1187 #undef __FUNC__ 1188 #define __FUNC__ /*<a name=""></a>*/"MatILUDTFactor" 1189 /*@C 1190 MatILUDTFactor - Performs a drop tolerance ILU factorization. 1191 1192 Collective on Mat 1193 1194 Input Parameters: 1195 + mat - the matrix 1196 . info - information about the factorization to be done 1197 . row - row permutation 1198 - col - column permutation 1199 1200 Output Parameters: 1201 . fact - the factored matrix 1202 1203 Level: developer 1204 1205 Notes: 1206 Most users should employ the simplified SLES interface for linear solvers 1207 instead of working directly with matrix algebra routines such as this. 1208 See, e.g., SLESCreate(). 1209 1210 This is currently only supported for the SeqAIJ matrix format using code 1211 from Yousef Saad's SPARSEKIT2 package (translated to C with f2c) and/or 1212 Matlab. SPARSEKIT2 is copyrighted by Yousef Saad with the GNU copyright 1213 and thus can be distributed with PETSc. 1214 1215 Concepts: matrices^ILUDT factorization 1216 1217 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 1218 @*/ 1219 int MatILUDTFactor(Mat mat,MatILUInfo *info,IS row,IS col,Mat *fact) 1220 { 1221 int ierr; 1222 1223 PetscFunctionBegin; 1224 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1225 PetscValidType(mat); 1226 MatPreallocated(mat); 1227 PetscValidPointer(fact); 1228 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1229 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1230 if (!mat->ops->iludtfactor) SETERRQ(PETSC_ERR_SUP,""); 1231 1232 ierr = PLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1233 ierr = (*mat->ops->iludtfactor)(mat,info,row,col,fact);CHKERRQ(ierr); 1234 ierr = PLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1235 1236 PetscFunctionReturn(0); 1237 } 1238 1239 #undef __FUNC__ 1240 #define __FUNC__ /*<a name=""></a>*/"MatLUFactor" 1241 /*@ 1242 MatLUFactor - Performs in-place LU factorization of matrix. 1243 1244 Collective on Mat 1245 1246 Input Parameters: 1247 + mat - the matrix 1248 . row - row permutation 1249 . col - column permutation 1250 - info - options for factorization, includes 1251 $ fill - expected fill as ratio of original fill. 1252 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 1253 $ Run with the option -log_info to determine an optimal value to use 1254 1255 Notes: 1256 Most users should employ the simplified SLES interface for linear solvers 1257 instead of working directly with matrix algebra routines such as this. 1258 See, e.g., SLESCreate(). 1259 1260 This changes the state of the matrix to a factored matrix; it cannot be used 1261 for example with MatSetValues() unless one first calls MatSetUnfactored(). 1262 1263 Level: developer 1264 1265 Concepts: matrices^LU factorization 1266 1267 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor(), 1268 MatGetOrdering(), MatSetUnfactored() 1269 1270 @*/ 1271 int MatLUFactor(Mat mat,IS row,IS col,MatLUInfo *info) 1272 { 1273 int ierr; 1274 1275 PetscFunctionBegin; 1276 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1277 PetscValidType(mat); 1278 MatPreallocated(mat); 1279 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1280 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1281 if (!mat->ops->lufactor) SETERRQ(PETSC_ERR_SUP,""); 1282 1283 ierr = PLogEventBegin(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 1284 ierr = (*mat->ops->lufactor)(mat,row,col,info);CHKERRQ(ierr); 1285 ierr = PLogEventEnd(MAT_LUFactor,mat,row,col,0);CHKERRQ(ierr); 1286 PetscFunctionReturn(0); 1287 } 1288 1289 #undef __FUNC__ 1290 #define __FUNC__ /*<a name=""></a>*/"MatILUFactor" 1291 /*@ 1292 MatILUFactor - Performs in-place ILU factorization of matrix. 1293 1294 Collective on Mat 1295 1296 Input Parameters: 1297 + mat - the matrix 1298 . row - row permutation 1299 . col - column permutation 1300 - info - structure containing 1301 $ levels - number of levels of fill. 1302 $ expected fill - as ratio of original fill. 1303 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 1304 missing diagonal entries) 1305 1306 Notes: 1307 Probably really in-place only when level of fill is zero, otherwise allocates 1308 new space to store factored matrix and deletes previous memory. 1309 1310 Most users should employ the simplified SLES interface for linear solvers 1311 instead of working directly with matrix algebra routines such as this. 1312 See, e.g., SLESCreate(). 1313 1314 Level: developer 1315 1316 Concepts: matrices^ILU factorization 1317 1318 .seealso: MatILUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 1319 @*/ 1320 int MatILUFactor(Mat mat,IS row,IS col,MatILUInfo *info) 1321 { 1322 int ierr; 1323 1324 PetscFunctionBegin; 1325 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1326 PetscValidType(mat); 1327 MatPreallocated(mat); 1328 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 1329 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1330 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1331 if (!mat->ops->ilufactor) SETERRQ(PETSC_ERR_SUP,""); 1332 1333 ierr = PLogEventBegin(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1334 ierr = (*mat->ops->ilufactor)(mat,row,col,info);CHKERRQ(ierr); 1335 ierr = PLogEventEnd(MAT_ILUFactor,mat,row,col,0);CHKERRQ(ierr); 1336 PetscFunctionReturn(0); 1337 } 1338 1339 #undef __FUNC__ 1340 #define __FUNC__ /*<a name=""></a>*/"MatLUFactorSymbolic" 1341 /*@ 1342 MatLUFactorSymbolic - Performs symbolic LU factorization of matrix. 1343 Call this routine before calling MatLUFactorNumeric(). 1344 1345 Collective on Mat 1346 1347 Input Parameters: 1348 + mat - the matrix 1349 . row, col - row and column permutations 1350 - info - options for factorization, includes 1351 $ fill - expected fill as ratio of original fill. 1352 $ dtcol - pivot tolerance (0 no pivot, 1 full column pivoting) 1353 $ Run with the option -log_info to determine an optimal value to use 1354 1355 Output Parameter: 1356 . fact - new matrix that has been symbolically factored 1357 1358 Notes: 1359 See the users manual for additional information about 1360 choosing the fill factor for better efficiency. 1361 1362 Most users should employ the simplified SLES interface for linear solvers 1363 instead of working directly with matrix algebra routines such as this. 1364 See, e.g., SLESCreate(). 1365 1366 Level: developer 1367 1368 Concepts: matrices^LU symbolic factorization 1369 1370 .seealso: MatLUFactor(), MatLUFactorNumeric(), MatCholeskyFactor() 1371 @*/ 1372 int MatLUFactorSymbolic(Mat mat,IS row,IS col,MatLUInfo *info,Mat *fact) 1373 { 1374 int ierr; 1375 1376 PetscFunctionBegin; 1377 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1378 PetscValidType(mat); 1379 MatPreallocated(mat); 1380 PetscValidPointer(fact); 1381 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1382 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1383 if (!mat->ops->lufactorsymbolic) SETERRQ(PETSC_ERR_SUP,""); 1384 1385 ierr = PLogEventBegin(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 1386 ierr = (*mat->ops->lufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 1387 ierr = PLogEventEnd(MAT_LUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 1388 PetscFunctionReturn(0); 1389 } 1390 1391 #undef __FUNC__ 1392 #define __FUNC__ /*<a name=""></a>*/"MatLUFactorNumeric" 1393 /*@ 1394 MatLUFactorNumeric - Performs numeric LU factorization of a matrix. 1395 Call this routine after first calling MatLUFactorSymbolic(). 1396 1397 Collective on Mat 1398 1399 Input Parameters: 1400 + mat - the matrix 1401 - fact - the matrix generated for the factor, from MatLUFactorSymbolic() 1402 1403 Notes: 1404 See MatLUFactor() for in-place factorization. See 1405 MatCholeskyFactorNumeric() for the symmetric, positive definite case. 1406 1407 Most users should employ the simplified SLES interface for linear solvers 1408 instead of working directly with matrix algebra routines such as this. 1409 See, e.g., SLESCreate(). 1410 1411 Level: developer 1412 1413 Concepts: matrices^LU numeric factorization 1414 1415 .seealso: MatLUFactorSymbolic(), MatLUFactor(), MatCholeskyFactor() 1416 @*/ 1417 int MatLUFactorNumeric(Mat mat,Mat *fact) 1418 { 1419 int ierr; 1420 PetscTruth flg; 1421 1422 PetscFunctionBegin; 1423 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1424 PetscValidType(mat); 1425 MatPreallocated(mat); 1426 PetscValidPointer(fact); 1427 PetscValidHeaderSpecific(*fact,MAT_COOKIE); 1428 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1429 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 1430 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dimensions are different %d should = %d %d should = %d", 1431 mat->M,(*fact)->M,mat->N,(*fact)->N); 1432 } 1433 if (!(*fact)->ops->lufactornumeric) SETERRQ(PETSC_ERR_SUP,""); 1434 1435 ierr = PLogEventBegin(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1436 ierr = (*(*fact)->ops->lufactornumeric)(mat,fact);CHKERRQ(ierr); 1437 ierr = PLogEventEnd(MAT_LUFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1438 ierr = OptionsHasName(PETSC_NULL,"-mat_view_draw",&flg);CHKERRQ(ierr); 1439 if (flg) { 1440 ierr = OptionsHasName(PETSC_NULL,"-mat_view_contour",&flg);CHKERRQ(ierr); 1441 if (flg) { 1442 ierr = ViewerPushFormat(VIEWER_DRAW_(mat->comm),VIEWER_FORMAT_DRAW_CONTOUR,0);CHKERRQ(ierr); 1443 } 1444 ierr = MatView(*fact,VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 1445 ierr = ViewerFlush(VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 1446 if (flg) { 1447 ierr = ViewerPopFormat(VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 1448 } 1449 } 1450 PetscFunctionReturn(0); 1451 } 1452 1453 #undef __FUNC__ 1454 #define __FUNC__ /*<a name=""></a>*/"MatCholeskyFactor" 1455 /*@ 1456 MatCholeskyFactor - Performs in-place Cholesky factorization of a 1457 symmetric matrix. 1458 1459 Collective on Mat 1460 1461 Input Parameters: 1462 + mat - the matrix 1463 . perm - row and column permutations 1464 - f - expected fill as ratio of original fill 1465 1466 Notes: 1467 See MatLUFactor() for the nonsymmetric case. See also 1468 MatCholeskyFactorSymbolic(), and MatCholeskyFactorNumeric(). 1469 1470 Most users should employ the simplified SLES interface for linear solvers 1471 instead of working directly with matrix algebra routines such as this. 1472 See, e.g., SLESCreate(). 1473 1474 Level: developer 1475 1476 Concepts: matrices^Cholesky factorization 1477 1478 .seealso: MatLUFactor(), MatCholeskyFactorSymbolic(), MatCholeskyFactorNumeric() 1479 MatGetOrdering() 1480 1481 @*/ 1482 int MatCholeskyFactor(Mat mat,IS perm,PetscReal f) 1483 { 1484 int ierr; 1485 1486 PetscFunctionBegin; 1487 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1488 PetscValidType(mat); 1489 MatPreallocated(mat); 1490 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 1491 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1492 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1493 if (!mat->ops->choleskyfactor) SETERRQ(PETSC_ERR_SUP,""); 1494 1495 ierr = PLogEventBegin(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 1496 ierr = (*mat->ops->choleskyfactor)(mat,perm,f);CHKERRQ(ierr); 1497 ierr = PLogEventEnd(MAT_CholeskyFactor,mat,perm,0,0);CHKERRQ(ierr); 1498 PetscFunctionReturn(0); 1499 } 1500 1501 #undef __FUNC__ 1502 #define __FUNC__ /*<a name=""></a>*/"MatCholeskyFactorSymbolic" 1503 /*@ 1504 MatCholeskyFactorSymbolic - Performs symbolic Cholesky factorization 1505 of a symmetric matrix. 1506 1507 Collective on Mat 1508 1509 Input Parameters: 1510 + mat - the matrix 1511 . perm - row and column permutations 1512 - f - expected fill as ratio of original 1513 1514 Output Parameter: 1515 . fact - the factored matrix 1516 1517 Notes: 1518 See MatLUFactorSymbolic() for the nonsymmetric case. See also 1519 MatCholeskyFactor() and MatCholeskyFactorNumeric(). 1520 1521 Most users should employ the simplified SLES interface for linear solvers 1522 instead of working directly with matrix algebra routines such as this. 1523 See, e.g., SLESCreate(). 1524 1525 Level: developer 1526 1527 Concepts: matrices^Cholesky symbolic factorization 1528 1529 .seealso: MatLUFactorSymbolic(), MatCholeskyFactor(), MatCholeskyFactorNumeric() 1530 MatGetOrdering() 1531 1532 @*/ 1533 int MatCholeskyFactorSymbolic(Mat mat,IS perm,PetscReal f,Mat *fact) 1534 { 1535 int ierr; 1536 1537 PetscFunctionBegin; 1538 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1539 PetscValidType(mat); 1540 MatPreallocated(mat); 1541 PetscValidPointer(fact); 1542 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"Matrix must be square"); 1543 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1544 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 1545 if (!mat->ops->choleskyfactorsymbolic) SETERRQ(PETSC_ERR_SUP,""); 1546 1547 ierr = PLogEventBegin(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 1548 ierr = (*mat->ops->choleskyfactorsymbolic)(mat,perm,f,fact);CHKERRQ(ierr); 1549 ierr = PLogEventEnd(MAT_CholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 1550 PetscFunctionReturn(0); 1551 } 1552 1553 #undef __FUNC__ 1554 #define __FUNC__ /*<a name=""></a>*/"MatCholeskyFactorNumeric" 1555 /*@ 1556 MatCholeskyFactorNumeric - Performs numeric Cholesky factorization 1557 of a symmetric matrix. Call this routine after first calling 1558 MatCholeskyFactorSymbolic(). 1559 1560 Collective on Mat 1561 1562 Input Parameter: 1563 . mat - the initial matrix 1564 1565 Output Parameter: 1566 . fact - the factored matrix 1567 1568 Notes: 1569 Most users should employ the simplified SLES interface for linear solvers 1570 instead of working directly with matrix algebra routines such as this. 1571 See, e.g., SLESCreate(). 1572 1573 Level: developer 1574 1575 Concepts: matrices^Cholesky numeric factorization 1576 1577 .seealso: MatCholeskyFactorSymbolic(), MatCholeskyFactor(), MatLUFactorNumeric() 1578 @*/ 1579 int MatCholeskyFactorNumeric(Mat mat,Mat *fact) 1580 { 1581 int ierr; 1582 1583 PetscFunctionBegin; 1584 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1585 PetscValidType(mat); 1586 MatPreallocated(mat); 1587 PetscValidPointer(fact); 1588 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1589 if (!(*fact)->ops->choleskyfactornumeric) SETERRQ(PETSC_ERR_SUP,""); 1590 if (mat->M != (*fact)->M || mat->N != (*fact)->N) { 1591 SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat mat,Mat *fact: global dim %d should = %d %d should = %d", 1592 mat->M,(*fact)->M,mat->N,(*fact)->N); 1593 } 1594 1595 ierr = PLogEventBegin(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1596 ierr = (*(*fact)->ops->choleskyfactornumeric)(mat,fact);CHKERRQ(ierr); 1597 ierr = PLogEventEnd(MAT_CholeskyFactorNumeric,mat,*fact,0,0);CHKERRQ(ierr); 1598 PetscFunctionReturn(0); 1599 } 1600 1601 /* ----------------------------------------------------------------*/ 1602 #undef __FUNC__ 1603 #define __FUNC__ /*<a name=""></a>*/"MatSolve" 1604 /*@ 1605 MatSolve - Solves A x = b, given a factored matrix. 1606 1607 Collective on Mat and Vec 1608 1609 Input Parameters: 1610 + mat - the factored matrix 1611 - b - the right-hand-side vector 1612 1613 Output Parameter: 1614 . x - the result vector 1615 1616 Notes: 1617 The vectors b and x cannot be the same. I.e., one cannot 1618 call MatSolve(A,x,x). 1619 1620 Notes: 1621 Most users should employ the simplified SLES interface for linear solvers 1622 instead of working directly with matrix algebra routines such as this. 1623 See, e.g., SLESCreate(). 1624 1625 Level: developer 1626 1627 Concepts: matrices^triangular solves 1628 1629 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd() 1630 @*/ 1631 int MatSolve(Mat mat,Vec b,Vec x) 1632 { 1633 int ierr; 1634 1635 PetscFunctionBegin; 1636 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1637 PetscValidType(mat); 1638 MatPreallocated(mat); 1639 PetscValidHeaderSpecific(b,VEC_COOKIE); 1640 PetscValidHeaderSpecific(x,VEC_COOKIE); 1641 PetscCheckSameComm(mat,b); 1642 PetscCheckSameComm(mat,x); 1643 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1644 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1645 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 1646 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N); 1647 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n); 1648 if (mat->M == 0 && mat->N == 0) PetscFunctionReturn(0); 1649 1650 if (!mat->ops->solve) SETERRQ(PETSC_ERR_SUP,""); 1651 ierr = PLogEventBegin(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 1652 ierr = (*mat->ops->solve)(mat,b,x);CHKERRQ(ierr); 1653 ierr = PLogEventEnd(MAT_Solve,mat,b,x,0);CHKERRQ(ierr); 1654 PetscFunctionReturn(0); 1655 } 1656 1657 #undef __FUNC__ 1658 #define __FUNC__ /*<a name=""></a>*/"MatForwardSolve" 1659 /* @ 1660 MatForwardSolve - Solves L x = b, given a factored matrix, A = LU. 1661 1662 Collective on Mat and Vec 1663 1664 Input Parameters: 1665 + mat - the factored matrix 1666 - b - the right-hand-side vector 1667 1668 Output Parameter: 1669 . x - the result vector 1670 1671 Notes: 1672 MatSolve() should be used for most applications, as it performs 1673 a forward solve followed by a backward solve. 1674 1675 The vectors b and x cannot be the same. I.e., one cannot 1676 call MatForwardSolve(A,x,x). 1677 1678 Most users should employ the simplified SLES interface for linear solvers 1679 instead of working directly with matrix algebra routines such as this. 1680 See, e.g., SLESCreate(). 1681 1682 Level: developer 1683 1684 Concepts: matrices^forward solves 1685 1686 .seealso: MatSolve(), MatBackwardSolve() 1687 @ */ 1688 int MatForwardSolve(Mat mat,Vec b,Vec x) 1689 { 1690 int ierr; 1691 1692 PetscFunctionBegin; 1693 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1694 PetscValidType(mat); 1695 MatPreallocated(mat); 1696 PetscValidHeaderSpecific(b,VEC_COOKIE); 1697 PetscValidHeaderSpecific(x,VEC_COOKIE); 1698 PetscCheckSameComm(mat,b); 1699 PetscCheckSameComm(mat,x); 1700 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1701 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1702 if (!mat->ops->forwardsolve) SETERRQ(PETSC_ERR_SUP,""); 1703 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 1704 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N); 1705 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n); 1706 1707 ierr = PLogEventBegin(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 1708 ierr = (*mat->ops->forwardsolve)(mat,b,x);CHKERRQ(ierr); 1709 ierr = PLogEventEnd(MAT_ForwardSolve,mat,b,x,0);CHKERRQ(ierr); 1710 PetscFunctionReturn(0); 1711 } 1712 1713 #undef __FUNC__ 1714 #define __FUNC__ /*<a name=""></a>*/"MatBackwardSolve" 1715 /* @ 1716 MatBackwardSolve - Solves U x = b, given a factored matrix, A = LU. 1717 1718 Collective on Mat and Vec 1719 1720 Input Parameters: 1721 + mat - the factored matrix 1722 - b - the right-hand-side vector 1723 1724 Output Parameter: 1725 . x - the result vector 1726 1727 Notes: 1728 MatSolve() should be used for most applications, as it performs 1729 a forward solve followed by a backward solve. 1730 1731 The vectors b and x cannot be the same. I.e., one cannot 1732 call MatBackwardSolve(A,x,x). 1733 1734 Most users should employ the simplified SLES interface for linear solvers 1735 instead of working directly with matrix algebra routines such as this. 1736 See, e.g., SLESCreate(). 1737 1738 Level: developer 1739 1740 Concepts: matrices^backward solves 1741 1742 .seealso: MatSolve(), MatForwardSolve() 1743 @ */ 1744 int MatBackwardSolve(Mat mat,Vec b,Vec x) 1745 { 1746 int ierr; 1747 1748 PetscFunctionBegin; 1749 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1750 PetscValidType(mat); 1751 MatPreallocated(mat); 1752 PetscValidHeaderSpecific(b,VEC_COOKIE); 1753 PetscValidHeaderSpecific(x,VEC_COOKIE); 1754 PetscCheckSameComm(mat,b); 1755 PetscCheckSameComm(mat,x); 1756 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1757 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1758 if (!mat->ops->backwardsolve) SETERRQ(PETSC_ERR_SUP,""); 1759 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 1760 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N); 1761 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n); 1762 1763 ierr = PLogEventBegin(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 1764 ierr = (*mat->ops->backwardsolve)(mat,b,x);CHKERRQ(ierr); 1765 ierr = PLogEventEnd(MAT_BackwardSolve,mat,b,x,0);CHKERRQ(ierr); 1766 PetscFunctionReturn(0); 1767 } 1768 1769 #undef __FUNC__ 1770 #define __FUNC__ /*<a name=""></a>*/"MatSolveAdd" 1771 /*@ 1772 MatSolveAdd - Computes x = y + inv(A)*b, given a factored matrix. 1773 1774 Collective on Mat and Vec 1775 1776 Input Parameters: 1777 + mat - the factored matrix 1778 . b - the right-hand-side vector 1779 - y - the vector to be added to 1780 1781 Output Parameter: 1782 . x - the result vector 1783 1784 Notes: 1785 The vectors b and x cannot be the same. I.e., one cannot 1786 call MatSolveAdd(A,x,y,x). 1787 1788 Most users should employ the simplified SLES interface for linear solvers 1789 instead of working directly with matrix algebra routines such as this. 1790 See, e.g., SLESCreate(). 1791 1792 Level: developer 1793 1794 Concepts: matrices^triangular solves 1795 1796 .seealso: MatSolve(), MatSolveTranspose(), MatSolveTransposeAdd() 1797 @*/ 1798 int MatSolveAdd(Mat mat,Vec b,Vec y,Vec x) 1799 { 1800 Scalar one = 1.0; 1801 Vec tmp; 1802 int ierr; 1803 1804 PetscFunctionBegin; 1805 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1806 PetscValidType(mat); 1807 MatPreallocated(mat); 1808 PetscValidHeaderSpecific(y,VEC_COOKIE); 1809 PetscValidHeaderSpecific(b,VEC_COOKIE); 1810 PetscValidHeaderSpecific(x,VEC_COOKIE); 1811 PetscCheckSameComm(mat,b); 1812 PetscCheckSameComm(mat,y); 1813 PetscCheckSameComm(mat,x); 1814 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1815 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1816 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 1817 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N); 1818 if (mat->M != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->M,y->N); 1819 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n); 1820 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n); 1821 1822 ierr = PLogEventBegin(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 1823 if (mat->ops->solveadd) { 1824 ierr = (*mat->ops->solveadd)(mat,b,y,x);CHKERRQ(ierr); 1825 } else { 1826 /* do the solve then the add manually */ 1827 if (x != y) { 1828 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 1829 ierr = VecAXPY(&one,y,x);CHKERRQ(ierr); 1830 } else { 1831 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 1832 PLogObjectParent(mat,tmp); 1833 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 1834 ierr = MatSolve(mat,b,x);CHKERRQ(ierr); 1835 ierr = VecAXPY(&one,tmp,x);CHKERRQ(ierr); 1836 ierr = VecDestroy(tmp);CHKERRQ(ierr); 1837 } 1838 } 1839 ierr = PLogEventEnd(MAT_SolveAdd,mat,b,x,y);CHKERRQ(ierr); 1840 PetscFunctionReturn(0); 1841 } 1842 1843 #undef __FUNC__ 1844 #define __FUNC__ /*<a name=""></a>*/"MatSolveTranspose" 1845 /*@ 1846 MatSolveTranspose - Solves A' x = b, given a factored matrix. 1847 1848 Collective on Mat and Vec 1849 1850 Input Parameters: 1851 + mat - the factored matrix 1852 - b - the right-hand-side vector 1853 1854 Output Parameter: 1855 . x - the result vector 1856 1857 Notes: 1858 The vectors b and x cannot be the same. I.e., one cannot 1859 call MatSolveTranspose(A,x,x). 1860 1861 Most users should employ the simplified SLES interface for linear solvers 1862 instead of working directly with matrix algebra routines such as this. 1863 See, e.g., SLESCreate(). 1864 1865 Level: developer 1866 1867 Concepts: matrices^triangular solves 1868 1869 .seealso: MatSolve(), MatSolveAdd(), MatSolveTransposeAdd() 1870 @*/ 1871 int MatSolveTranspose(Mat mat,Vec b,Vec x) 1872 { 1873 int ierr; 1874 1875 PetscFunctionBegin; 1876 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1877 PetscValidType(mat); 1878 MatPreallocated(mat); 1879 PetscValidHeaderSpecific(b,VEC_COOKIE); 1880 PetscValidHeaderSpecific(x,VEC_COOKIE); 1881 PetscCheckSameComm(mat,b); 1882 PetscCheckSameComm(mat,x); 1883 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1884 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1885 if (!mat->ops->solvetranspose) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s",mat->type_name); 1886 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N); 1887 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N); 1888 1889 ierr = PLogEventBegin(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 1890 ierr = (*mat->ops->solvetranspose)(mat,b,x);CHKERRQ(ierr); 1891 ierr = PLogEventEnd(MAT_SolveTranspose,mat,b,x,0);CHKERRQ(ierr); 1892 PetscFunctionReturn(0); 1893 } 1894 1895 #undef __FUNC__ 1896 #define __FUNC__ /*<a name=""></a>*/"MatSolveTransposeAdd" 1897 /*@ 1898 MatSolveTransposeAdd - Computes x = y + inv(Transpose(A)) b, given a 1899 factored matrix. 1900 1901 Collective on Mat and Vec 1902 1903 Input Parameters: 1904 + mat - the factored matrix 1905 . b - the right-hand-side vector 1906 - y - the vector to be added to 1907 1908 Output Parameter: 1909 . x - the result vector 1910 1911 Notes: 1912 The vectors b and x cannot be the same. I.e., one cannot 1913 call MatSolveTransposeAdd(A,x,y,x). 1914 1915 Most users should employ the simplified SLES interface for linear solvers 1916 instead of working directly with matrix algebra routines such as this. 1917 See, e.g., SLESCreate(). 1918 1919 Level: developer 1920 1921 Concepts: matrices^triangular solves 1922 1923 .seealso: MatSolve(), MatSolveAdd(), MatSolveTranspose() 1924 @*/ 1925 int MatSolveTransposeAdd(Mat mat,Vec b,Vec y,Vec x) 1926 { 1927 Scalar one = 1.0; 1928 int ierr; 1929 Vec tmp; 1930 1931 PetscFunctionBegin; 1932 PetscValidHeaderSpecific(mat,MAT_COOKIE); 1933 PetscValidType(mat); 1934 MatPreallocated(mat); 1935 PetscValidHeaderSpecific(y,VEC_COOKIE); 1936 PetscValidHeaderSpecific(b,VEC_COOKIE); 1937 PetscValidHeaderSpecific(x,VEC_COOKIE); 1938 PetscCheckSameComm(mat,b); 1939 PetscCheckSameComm(mat,y); 1940 PetscCheckSameComm(mat,x); 1941 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 1942 if (!mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 1943 if (mat->M != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->M,x->N); 1944 if (mat->N != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->N,b->N); 1945 if (mat->N != y->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec y: global dim %d %d",mat->N,y->N); 1946 if (x->n != y->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Vec x,Vec y: local dim %d %d",x->n,y->n); 1947 1948 ierr = PLogEventBegin(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 1949 if (mat->ops->solvetransposeadd) { 1950 ierr = (*mat->ops->solvetransposeadd)(mat,b,y,x);CHKERRQ(ierr); 1951 } else { 1952 /* do the solve then the add manually */ 1953 if (x != y) { 1954 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 1955 ierr = VecAXPY(&one,y,x);CHKERRQ(ierr); 1956 } else { 1957 ierr = VecDuplicate(x,&tmp);CHKERRQ(ierr); 1958 PLogObjectParent(mat,tmp); 1959 ierr = VecCopy(x,tmp);CHKERRQ(ierr); 1960 ierr = MatSolveTranspose(mat,b,x);CHKERRQ(ierr); 1961 ierr = VecAXPY(&one,tmp,x);CHKERRQ(ierr); 1962 ierr = VecDestroy(tmp);CHKERRQ(ierr); 1963 } 1964 } 1965 ierr = PLogEventEnd(MAT_SolveTransposeAdd,mat,b,x,y);CHKERRQ(ierr); 1966 PetscFunctionReturn(0); 1967 } 1968 /* ----------------------------------------------------------------*/ 1969 1970 #undef __FUNC__ 1971 #define __FUNC__ /*<a name=""></a>*/"MatRelax" 1972 /*@ 1973 MatRelax - Computes one relaxation sweep. 1974 1975 Collective on Mat and Vec 1976 1977 Input Parameters: 1978 + mat - the matrix 1979 . b - the right hand side 1980 . omega - the relaxation factor 1981 . flag - flag indicating the type of SOR (see below) 1982 . shift - diagonal shift 1983 - its - the number of iterations 1984 1985 Output Parameters: 1986 . x - the solution (can contain an initial guess) 1987 1988 SOR Flags: 1989 . SOR_FORWARD_SWEEP - forward SOR 1990 . SOR_BACKWARD_SWEEP - backward SOR 1991 . SOR_SYMMETRIC_SWEEP - SSOR (symmetric SOR) 1992 . SOR_LOCAL_FORWARD_SWEEP - local forward SOR 1993 . SOR_LOCAL_BACKWARD_SWEEP - local forward SOR 1994 . SOR_LOCAL_SYMMETRIC_SWEEP - local SSOR 1995 . SOR_APPLY_UPPER, SOR_APPLY_LOWER - applies 1996 upper/lower triangular part of matrix to 1997 vector (with omega) 1998 . SOR_ZERO_INITIAL_GUESS - zero initial guess 1999 2000 Notes: 2001 SOR_LOCAL_FORWARD_SWEEP, SOR_LOCAL_BACKWARD_SWEEP, and 2002 SOR_LOCAL_SYMMETRIC_SWEEP perform seperate independent smoothings 2003 on each processor. 2004 2005 Application programmers will not generally use MatRelax() directly, 2006 but instead will employ the SLES/PC interface. 2007 2008 Notes for Advanced Users: 2009 The flags are implemented as bitwise inclusive or operations. 2010 For example, use (SOR_ZERO_INITIAL_GUESS | SOR_SYMMETRIC_SWEEP) 2011 to specify a zero initial guess for SSOR. 2012 2013 Most users should employ the simplified SLES interface for linear solvers 2014 instead of working directly with matrix algebra routines such as this. 2015 See, e.g., SLESCreate(). 2016 2017 Level: developer 2018 2019 Concepts: matrices^relaxation 2020 Concepts: matrices^SOR 2021 Concepts: matrices^Gauss-Seidel 2022 2023 @*/ 2024 int MatRelax(Mat mat,Vec b,PetscReal omega,MatSORType flag,PetscReal shift,int its,Vec x) 2025 { 2026 int ierr; 2027 2028 PetscFunctionBegin; 2029 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2030 PetscValidType(mat); 2031 MatPreallocated(mat); 2032 PetscValidHeaderSpecific(b,VEC_COOKIE); 2033 PetscValidHeaderSpecific(x,VEC_COOKIE); 2034 PetscCheckSameComm(mat,b); 2035 PetscCheckSameComm(mat,x); 2036 if (!mat->ops->relax) SETERRQ(PETSC_ERR_SUP,""); 2037 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2038 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2039 if (mat->N != x->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec x: global dim %d %d",mat->N,x->N); 2040 if (mat->M != b->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: global dim %d %d",mat->M,b->N); 2041 if (mat->m != b->n) SETERRQ2(PETSC_ERR_ARG_SIZ,"Mat mat,Vec b: local dim %d %d",mat->m,b->n); 2042 2043 ierr = PLogEventBegin(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2044 ierr =(*mat->ops->relax)(mat,b,omega,flag,shift,its,x);CHKERRQ(ierr); 2045 ierr = PLogEventEnd(MAT_Relax,mat,b,x,0);CHKERRQ(ierr); 2046 PetscFunctionReturn(0); 2047 } 2048 2049 #undef __FUNC__ 2050 #define __FUNC__ /*<a name=""></a>*/"MatCopy_Basic" 2051 /* 2052 Default matrix copy routine. 2053 */ 2054 int MatCopy_Basic(Mat A,Mat B,MatStructure str) 2055 { 2056 int ierr,i,rstart,rend,nz,*cwork; 2057 Scalar *vwork; 2058 2059 PetscFunctionBegin; 2060 ierr = MatZeroEntries(B);CHKERRQ(ierr); 2061 ierr = MatGetOwnershipRange(A,&rstart,&rend);CHKERRQ(ierr); 2062 for (i=rstart; i<rend; i++) { 2063 ierr = MatGetRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2064 ierr = MatSetValues(B,1,&i,nz,cwork,vwork,INSERT_VALUES);CHKERRQ(ierr); 2065 ierr = MatRestoreRow(A,i,&nz,&cwork,&vwork);CHKERRQ(ierr); 2066 } 2067 ierr = MatAssemblyBegin(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2068 ierr = MatAssemblyEnd(B,MAT_FINAL_ASSEMBLY);CHKERRQ(ierr); 2069 PetscFunctionReturn(0); 2070 } 2071 2072 #undef __FUNC__ 2073 #define __FUNC__ /*<a name=""></a>*/"MatCopy" 2074 /*@C 2075 MatCopy - Copys a matrix to another matrix. 2076 2077 Collective on Mat 2078 2079 Input Parameters: 2080 + A - the matrix 2081 - str - SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN 2082 2083 Output Parameter: 2084 . B - where the copy is put 2085 2086 Notes: 2087 If you use SAME_NONZERO_PATTERN then the zero matrices had better have the 2088 same nonzero pattern or the routine will crash. 2089 2090 MatCopy() copies the matrix entries of a matrix to another existing 2091 matrix (after first zeroing the second matrix). A related routine is 2092 MatConvert(), which first creates a new matrix and then copies the data. 2093 2094 Level: intermediate 2095 2096 Concepts: matrices^copying 2097 2098 .seealso: MatConvert() 2099 @*/ 2100 int MatCopy(Mat A,Mat B,MatStructure str) 2101 { 2102 int ierr; 2103 2104 PetscFunctionBegin; 2105 PetscValidHeaderSpecific(A,MAT_COOKIE); 2106 PetscValidHeaderSpecific(B,MAT_COOKIE); 2107 PetscValidType(A); 2108 MatPreallocated(A); 2109 PetscValidType(B); 2110 MatPreallocated(B); 2111 PetscCheckSameComm(A,B); 2112 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2113 if (A->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2114 if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d",A->M,B->M, 2115 A->N,B->N); 2116 2117 ierr = PLogEventBegin(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 2118 if (A->ops->copy) { 2119 ierr = (*A->ops->copy)(A,B,str);CHKERRQ(ierr); 2120 } else { /* generic conversion */ 2121 ierr = MatCopy_Basic(A,B,str);CHKERRQ(ierr); 2122 } 2123 ierr = PLogEventEnd(MAT_Copy,A,B,0,0);CHKERRQ(ierr); 2124 PetscFunctionReturn(0); 2125 } 2126 2127 #include "petscsys.h" 2128 PetscTruth MatConvertRegisterAllCalled = PETSC_FALSE; 2129 FList MatConvertList = 0; 2130 2131 #undef __FUNC__ 2132 #define __FUNC__ /*<a name=""></a>*/"MatConvertRegister" 2133 /*@C 2134 MatConvertRegister - Allows one to register a routine that reads matrices 2135 from a binary file for a particular matrix type. 2136 2137 Not Collective 2138 2139 Input Parameters: 2140 + type - the type of matrix (defined in include/petscmat.h), for example, MATSEQAIJ. 2141 - Converter - the function that reads the matrix from the binary file. 2142 2143 Level: developer 2144 2145 .seealso: MatConvertRegisterAll(), MatConvert() 2146 2147 @*/ 2148 int MatConvertRegister(char *sname,char *path,char *name,int (*function)(Mat,MatType,Mat*)) 2149 { 2150 int ierr; 2151 char fullname[256]; 2152 2153 PetscFunctionBegin; 2154 ierr = FListConcat(path,name,fullname);CHKERRQ(ierr); 2155 ierr = FListAdd(&MatConvertList,sname,fullname,(int (*)(void*))function);CHKERRQ(ierr); 2156 PetscFunctionReturn(0); 2157 } 2158 2159 #undef __FUNC__ 2160 #define __FUNC__ /*<a name=""></a>*/"MatConvert" 2161 /*@C 2162 MatConvert - Converts a matrix to another matrix, either of the same 2163 or different type. 2164 2165 Collective on Mat 2166 2167 Input Parameters: 2168 + mat - the matrix 2169 - newtype - new matrix type. Use MATSAME to create a new matrix of the 2170 same type as the original matrix. 2171 2172 Output Parameter: 2173 . M - pointer to place new matrix 2174 2175 Notes: 2176 MatConvert() first creates a new matrix and then copies the data from 2177 the first matrix. A related routine is MatCopy(), which copies the matrix 2178 entries of one matrix to another already existing matrix context. 2179 2180 Level: intermediate 2181 2182 Concepts: matrices^converting between storage formats 2183 2184 .seealso: MatCopy(), MatDuplicate() 2185 @*/ 2186 int MatConvert(Mat mat,MatType newtype,Mat *M) 2187 { 2188 int ierr; 2189 PetscTruth sametype,issame,flg; 2190 char convname[256],mtype[256]; 2191 2192 PetscFunctionBegin; 2193 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2194 PetscValidType(mat); 2195 MatPreallocated(mat); 2196 PetscValidPointer(M); 2197 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2198 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2199 2200 ierr = OptionsGetString(PETSC_NULL,"-matconvert_type",mtype,256,&flg);CHKERRQ(ierr); 2201 if (flg) { 2202 newtype = mtype; 2203 } 2204 ierr = PLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2205 2206 ierr = PetscTypeCompare((PetscObject)mat,newtype,&sametype);CHKERRQ(ierr); 2207 ierr = PetscStrcmp(newtype,"same",&issame);CHKERRQ(ierr); 2208 if ((sametype || issame) && mat->ops->duplicate) { 2209 ierr = (*mat->ops->duplicate)(mat,MAT_COPY_VALUES,M);CHKERRQ(ierr); 2210 } else { 2211 int (*conv)(Mat,MatType,Mat*); 2212 ierr = PetscStrcpy(convname,"MatConvertTo_");CHKERRQ(ierr); 2213 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 2214 ierr = FListFind(mat->comm,MatConvertList,convname,(int(**)(void*))&conv);CHKERRQ(ierr); 2215 if (conv) { 2216 ierr = (*conv)(mat,newtype,M);CHKERRQ(ierr); 2217 } else { 2218 ierr = PetscStrcpy(convname,"MatConvert_");CHKERRQ(ierr); 2219 ierr = PetscStrcat(convname,mat->type_name);CHKERRQ(ierr); 2220 ierr = PetscStrcat(convname,"_");CHKERRQ(ierr); 2221 ierr = PetscStrcat(convname,newtype);CHKERRQ(ierr); 2222 ierr = PetscStrcat(convname,"_C");CHKERRQ(ierr); 2223 ierr = PetscObjectQueryFunction((PetscObject)mat,convname,(void**)&conv);CHKERRQ(ierr); 2224 if (conv) { 2225 ierr = (*conv)(mat,newtype,M);CHKERRQ(ierr); 2226 } else { 2227 if (mat->ops->convert) { 2228 ierr = (*mat->ops->convert)(mat,newtype,M);CHKERRQ(ierr); 2229 } else { 2230 ierr = MatConvert_Basic(mat,newtype,M);CHKERRQ(ierr); 2231 } 2232 } 2233 } 2234 } 2235 ierr = PLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2236 PetscFunctionReturn(0); 2237 } 2238 2239 2240 #undef __FUNC__ 2241 #define __FUNC__ /*<a name=""></a>*/"MatDuplicate" 2242 /*@C 2243 MatDuplicate - Duplicates a matrix including the non-zero structure. 2244 2245 Collective on Mat 2246 2247 Input Parameters: 2248 + mat - the matrix 2249 - op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy nonzero 2250 values as well or not 2251 2252 Output Parameter: 2253 . M - pointer to place new matrix 2254 2255 Level: intermediate 2256 2257 Concepts: matrices^duplicating 2258 2259 .seealso: MatCopy(), MatConvert() 2260 @*/ 2261 int MatDuplicate(Mat mat,MatDuplicateOption op,Mat *M) 2262 { 2263 int ierr; 2264 2265 PetscFunctionBegin; 2266 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2267 PetscValidType(mat); 2268 MatPreallocated(mat); 2269 PetscValidPointer(M); 2270 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2271 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2272 2273 *M = 0; 2274 ierr = PLogEventBegin(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2275 if (!mat->ops->duplicate) { 2276 SETERRQ(PETSC_ERR_SUP,"Not written for this matrix type"); 2277 } 2278 ierr = (*mat->ops->duplicate)(mat,op,M);CHKERRQ(ierr); 2279 ierr = PLogEventEnd(MAT_Convert,mat,0,0,0);CHKERRQ(ierr); 2280 PetscFunctionReturn(0); 2281 } 2282 2283 #undef __FUNC__ 2284 #define __FUNC__ /*<a name=""></a>*/"MatGetDiagonal" 2285 /*@ 2286 MatGetDiagonal - Gets the diagonal of a matrix. 2287 2288 Collective on Mat and Vec 2289 2290 Input Parameters: 2291 + mat - the matrix 2292 - v - the vector for storing the diagonal 2293 2294 Output Parameter: 2295 . v - the diagonal of the matrix 2296 2297 Notes: 2298 For the SeqAIJ matrix format, this routine may also be called 2299 on a LU factored matrix; in that case it routines the reciprocal of 2300 the diagonal entries in U. It returns the entries permuted by the 2301 row and column permutation used during the symbolic factorization. 2302 2303 Level: intermediate 2304 2305 Concepts: matrices^accessing diagonals 2306 2307 .seealso: MatGetRow(), MatGetSubmatrices(), MatGetSubmatrix(), MatGetRowMax() 2308 @*/ 2309 int MatGetDiagonal(Mat mat,Vec v) 2310 { 2311 int ierr; 2312 2313 PetscFunctionBegin; 2314 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2315 PetscValidType(mat); 2316 MatPreallocated(mat); 2317 PetscValidHeaderSpecific(v,VEC_COOKIE); 2318 /* PetscCheckSameComm(mat,v); Could be MPI vector but Seq matrix cause of two submatrix storage */ 2319 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2320 if (!mat->ops->getdiagonal) SETERRQ(PETSC_ERR_SUP,""); 2321 2322 ierr = (*mat->ops->getdiagonal)(mat,v);CHKERRQ(ierr); 2323 PetscFunctionReturn(0); 2324 } 2325 2326 #undef __FUNC__ 2327 #define __FUNC__ /*<a name=""></a>*/"MatGetRowMax" 2328 /*@ 2329 MatGetRowMax - Gets the maximum value (in absolute value) of each 2330 row of the matrix 2331 2332 Collective on Mat and Vec 2333 2334 Input Parameters: 2335 . mat - the matrix 2336 2337 Output Parameter: 2338 . v - the vector for storing the maximums 2339 2340 Level: intermediate 2341 2342 Concepts: matrices^getting row maximums 2343 2344 .seealso: MatGetDiagonal(), MatGetSubmatrices(), MatGetSubmatrix() 2345 @*/ 2346 int MatGetRowMax(Mat mat,Vec v) 2347 { 2348 int ierr; 2349 2350 PetscFunctionBegin; 2351 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2352 PetscValidType(mat); 2353 MatPreallocated(mat); 2354 PetscValidHeaderSpecific(v,VEC_COOKIE); 2355 /* PetscCheckSameComm(mat,v); Could be MPI vector but Seq matrix cause of two submatrix storage */ 2356 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2357 if (!mat->ops->getrowmax) SETERRQ(PETSC_ERR_SUP,""); 2358 2359 ierr = (*mat->ops->getrowmax)(mat,v);CHKERRQ(ierr); 2360 PetscFunctionReturn(0); 2361 } 2362 2363 #undef __FUNC__ 2364 #define __FUNC__ /*<a name=""></a>*/"MatTranspose" 2365 /*@C 2366 MatTranspose - Computes an in-place or out-of-place transpose of a matrix. 2367 2368 Collective on Mat 2369 2370 Input Parameter: 2371 . mat - the matrix to transpose 2372 2373 Output Parameters: 2374 . B - the transpose (or pass in PETSC_NULL for an in-place transpose) 2375 2376 Level: intermediate 2377 2378 Concepts: matrices^transposing 2379 2380 .seealso: MatMultTranspose(), MatMultTransposeAdd() 2381 @*/ 2382 int MatTranspose(Mat mat,Mat *B) 2383 { 2384 int ierr; 2385 2386 PetscFunctionBegin; 2387 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2388 PetscValidType(mat); 2389 MatPreallocated(mat); 2390 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2391 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2392 if (!mat->ops->transpose) SETERRQ(PETSC_ERR_SUP,""); 2393 ierr = (*mat->ops->transpose)(mat,B);CHKERRQ(ierr); 2394 PetscFunctionReturn(0); 2395 } 2396 2397 #undef __FUNC__ 2398 #define __FUNC__ /*<a name=""></a>*/"MatPermute" 2399 /*@C 2400 MatPermute - Creates a new matrix with rows and columns permuted from the 2401 original. 2402 2403 Collective on Mat 2404 2405 Input Parameters: 2406 + mat - the matrix to permute 2407 . row - row permutation, each processor supplies only the permutation for its rows 2408 - col - column permutation, each processor needs the entire column permutation, that is 2409 this is the same size as the total number of columns in the matrix 2410 2411 Output Parameters: 2412 . B - the permuted matrix 2413 2414 Level: advanced 2415 2416 Concepts: matrices^permuting 2417 2418 .seealso: MatGetOrdering() 2419 @*/ 2420 int MatPermute(Mat mat,IS row,IS col,Mat *B) 2421 { 2422 int ierr; 2423 2424 PetscFunctionBegin; 2425 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2426 PetscValidType(mat); 2427 MatPreallocated(mat); 2428 PetscValidHeaderSpecific(row,IS_COOKIE); 2429 PetscValidHeaderSpecific(col,IS_COOKIE); 2430 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2431 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2432 if (!mat->ops->permute) SETERRQ(PETSC_ERR_SUP,""); 2433 ierr = (*mat->ops->permute)(mat,row,col,B);CHKERRQ(ierr); 2434 PetscFunctionReturn(0); 2435 } 2436 2437 #undef __FUNC__ 2438 #define __FUNC__ /*<a name=""></a>*/"MatEqual" 2439 /*@ 2440 MatEqual - Compares two matrices. 2441 2442 Collective on Mat 2443 2444 Input Parameters: 2445 + A - the first matrix 2446 - B - the second matrix 2447 2448 Output Parameter: 2449 . flg - PETSC_TRUE if the matrices are equal; PETSC_FALSE otherwise. 2450 2451 Level: intermediate 2452 2453 Concepts: matrices^equality between 2454 @*/ 2455 int MatEqual(Mat A,Mat B,PetscTruth *flg) 2456 { 2457 int ierr; 2458 2459 PetscFunctionBegin; 2460 PetscValidHeaderSpecific(A,MAT_COOKIE); 2461 PetscValidHeaderSpecific(B,MAT_COOKIE); 2462 PetscValidType(A); 2463 MatPreallocated(A); 2464 PetscValidType(B); 2465 MatPreallocated(B); 2466 PetscValidIntPointer(flg); 2467 PetscCheckSameComm(A,B); 2468 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2469 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2470 if (A->M != B->M || A->N != B->N) SETERRQ4(PETSC_ERR_ARG_SIZ,"Mat A,Mat B: global dim %d %d %d %d", 2471 A->M,B->M,A->N,B->N); 2472 if (!A->ops->equal) SETERRQ(PETSC_ERR_SUP,""); 2473 ierr = (*A->ops->equal)(A,B,flg);CHKERRQ(ierr); 2474 PetscFunctionReturn(0); 2475 } 2476 2477 #undef __FUNC__ 2478 #define __FUNC__ /*<a name=""></a>*/"MatDiagonalScale" 2479 /*@ 2480 MatDiagonalScale - Scales a matrix on the left and right by diagonal 2481 matrices that are stored as vectors. Either of the two scaling 2482 matrices can be PETSC_NULL. 2483 2484 Collective on Mat 2485 2486 Input Parameters: 2487 + mat - the matrix to be scaled 2488 . l - the left scaling vector (or PETSC_NULL) 2489 - r - the right scaling vector (or PETSC_NULL) 2490 2491 Notes: 2492 MatDiagonalScale() computes A = LAR, where 2493 L = a diagonal matrix, R = a diagonal matrix 2494 2495 Level: intermediate 2496 2497 Concepts: matrices^diagonal scaling 2498 Concepts: diagonal scaling of matrices 2499 2500 .seealso: MatScale() 2501 @*/ 2502 int MatDiagonalScale(Mat mat,Vec l,Vec r) 2503 { 2504 int ierr; 2505 2506 PetscFunctionBegin; 2507 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2508 PetscValidType(mat); 2509 MatPreallocated(mat); 2510 if (!mat->ops->diagonalscale) SETERRQ(PETSC_ERR_SUP,""); 2511 if (l) {PetscValidHeaderSpecific(l,VEC_COOKIE);PetscCheckSameComm(mat,l);} 2512 if (r) {PetscValidHeaderSpecific(r,VEC_COOKIE);PetscCheckSameComm(mat,r);} 2513 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2514 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2515 2516 ierr = PLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 2517 ierr = (*mat->ops->diagonalscale)(mat,l,r);CHKERRQ(ierr); 2518 ierr = PLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 2519 PetscFunctionReturn(0); 2520 } 2521 2522 #undef __FUNC__ 2523 #define __FUNC__ /*<a name=""></a>*/"MatScale" 2524 /*@ 2525 MatScale - Scales all elements of a matrix by a given number. 2526 2527 Collective on Mat 2528 2529 Input Parameters: 2530 + mat - the matrix to be scaled 2531 - a - the scaling value 2532 2533 Output Parameter: 2534 . mat - the scaled matrix 2535 2536 Level: intermediate 2537 2538 Concepts: matrices^scaling all entries 2539 2540 .seealso: MatDiagonalScale() 2541 @*/ 2542 int MatScale(Scalar *a,Mat mat) 2543 { 2544 int ierr; 2545 2546 PetscFunctionBegin; 2547 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2548 PetscValidType(mat); 2549 MatPreallocated(mat); 2550 PetscValidScalarPointer(a); 2551 if (!mat->ops->scale) SETERRQ(PETSC_ERR_SUP,""); 2552 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2553 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2554 2555 ierr = PLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 2556 ierr = (*mat->ops->scale)(a,mat);CHKERRQ(ierr); 2557 ierr = PLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 2558 PetscFunctionReturn(0); 2559 } 2560 2561 #undef __FUNC__ 2562 #define __FUNC__ /*<a name=""></a>*/"MatNorm" 2563 /*@ 2564 MatNorm - Calculates various norms of a matrix. 2565 2566 Collective on Mat 2567 2568 Input Parameters: 2569 + mat - the matrix 2570 - type - the type of norm, NORM_1, NORM_2, NORM_FROBENIUS, NORM_INFINITY 2571 2572 Output Parameters: 2573 . norm - the resulting norm 2574 2575 Level: intermediate 2576 2577 Concepts: matrices^norm 2578 Concepts: norm^of matrix 2579 @*/ 2580 int MatNorm(Mat mat,NormType type,PetscReal *norm) 2581 { 2582 int ierr; 2583 2584 PetscFunctionBegin; 2585 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2586 PetscValidType(mat); 2587 MatPreallocated(mat); 2588 PetscValidScalarPointer(norm); 2589 2590 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2591 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2592 if (!mat->ops->norm) SETERRQ(PETSC_ERR_SUP,"Not for this matrix type"); 2593 ierr = (*mat->ops->norm)(mat,type,norm);CHKERRQ(ierr); 2594 PetscFunctionReturn(0); 2595 } 2596 2597 /* 2598 This variable is used to prevent counting of MatAssemblyBegin() that 2599 are called from within a MatAssemblyEnd(). 2600 */ 2601 static int MatAssemblyEnd_InUse = 0; 2602 #undef __FUNC__ 2603 #define __FUNC__ /*<a name=""></a>*/"MatAssemblyBegin" 2604 /*@ 2605 MatAssemblyBegin - Begins assembling the matrix. This routine should 2606 be called after completing all calls to MatSetValues(). 2607 2608 Collective on Mat 2609 2610 Input Parameters: 2611 + mat - the matrix 2612 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 2613 2614 Notes: 2615 MatSetValues() generally caches the values. The matrix is ready to 2616 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 2617 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 2618 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 2619 using the matrix. 2620 2621 Level: beginner 2622 2623 Concepts: matrices^assembling 2624 2625 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled() 2626 @*/ 2627 int MatAssemblyBegin(Mat mat,MatAssemblyType type) 2628 { 2629 int ierr; 2630 2631 PetscFunctionBegin; 2632 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2633 PetscValidType(mat); 2634 MatPreallocated(mat); 2635 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?"); 2636 if (mat->assembled) { 2637 mat->was_assembled = PETSC_TRUE; 2638 mat->assembled = PETSC_FALSE; 2639 } 2640 if (!MatAssemblyEnd_InUse) { 2641 ierr = PLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 2642 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 2643 ierr = PLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 2644 } else { 2645 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 2646 } 2647 PetscFunctionReturn(0); 2648 } 2649 2650 #undef __FUNC__ 2651 #define __FUNC__ /*<a name=""></a>*/"MatAssembed" 2652 /*@ 2653 MatAssembled - Indicates if a matrix has been assembled and is ready for 2654 use; for example, in matrix-vector product. 2655 2656 Collective on Mat 2657 2658 Input Parameter: 2659 . mat - the matrix 2660 2661 Output Parameter: 2662 . assembled - PETSC_TRUE or PETSC_FALSE 2663 2664 Level: advanced 2665 2666 Concepts: matrices^assembled? 2667 2668 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin() 2669 @*/ 2670 int MatAssembled(Mat mat,PetscTruth *assembled) 2671 { 2672 PetscFunctionBegin; 2673 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2674 PetscValidType(mat); 2675 MatPreallocated(mat); 2676 *assembled = mat->assembled; 2677 PetscFunctionReturn(0); 2678 } 2679 2680 #undef __FUNC__ 2681 #define __FUNC__ /*<a name=""></a>*/"MatView_Private" 2682 /* 2683 Processes command line options to determine if/how a matrix 2684 is to be viewed. Called by MatAssemblyEnd() and MatLoad(). 2685 */ 2686 int MatView_Private(Mat mat) 2687 { 2688 int ierr; 2689 PetscTruth flg; 2690 2691 PetscFunctionBegin; 2692 ierr = OptionsHasName(mat->prefix,"-mat_view_info",&flg);CHKERRQ(ierr); 2693 if (flg) { 2694 ierr = ViewerPushFormat(VIEWER_STDOUT_(mat->comm),VIEWER_FORMAT_ASCII_INFO,0);CHKERRQ(ierr); 2695 ierr = MatView(mat,VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2696 ierr = ViewerPopFormat(VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2697 } 2698 ierr = OptionsHasName(mat->prefix,"-mat_view_info_detailed",&flg);CHKERRQ(ierr); 2699 if (flg) { 2700 ierr = ViewerPushFormat(VIEWER_STDOUT_(mat->comm),VIEWER_FORMAT_ASCII_INFO_LONG,0);CHKERRQ(ierr); 2701 ierr = MatView(mat,VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2702 ierr = ViewerPopFormat(VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2703 } 2704 ierr = OptionsHasName(mat->prefix,"-mat_view",&flg);CHKERRQ(ierr); 2705 if (flg) { 2706 ierr = MatView(mat,VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2707 } 2708 ierr = OptionsHasName(mat->prefix,"-mat_view_matlab",&flg);CHKERRQ(ierr); 2709 if (flg) { 2710 ierr = ViewerPushFormat(VIEWER_STDOUT_(mat->comm),VIEWER_FORMAT_ASCII_MATLAB,"M");CHKERRQ(ierr); 2711 ierr = MatView(mat,VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2712 ierr = ViewerPopFormat(VIEWER_STDOUT_(mat->comm));CHKERRQ(ierr); 2713 } 2714 ierr = OptionsHasName(mat->prefix,"-mat_view_draw",&flg);CHKERRQ(ierr); 2715 if (flg) { 2716 ierr = OptionsHasName(mat->prefix,"-mat_view_contour",&flg);CHKERRQ(ierr); 2717 if (flg) { 2718 ViewerPushFormat(VIEWER_DRAW_(mat->comm),VIEWER_FORMAT_DRAW_CONTOUR,0);CHKERRQ(ierr); 2719 } 2720 ierr = MatView(mat,VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 2721 ierr = ViewerFlush(VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 2722 if (flg) { 2723 ViewerPopFormat(VIEWER_DRAW_(mat->comm));CHKERRQ(ierr); 2724 } 2725 } 2726 ierr = OptionsHasName(mat->prefix,"-mat_view_socket",&flg);CHKERRQ(ierr); 2727 if (flg) { 2728 ierr = MatView(mat,VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 2729 ierr = ViewerFlush(VIEWER_SOCKET_(mat->comm));CHKERRQ(ierr); 2730 } 2731 ierr = OptionsHasName(mat->prefix,"-mat_view_binary",&flg);CHKERRQ(ierr); 2732 if (flg) { 2733 ierr = MatView(mat,VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 2734 ierr = ViewerFlush(VIEWER_BINARY_(mat->comm));CHKERRQ(ierr); 2735 } 2736 PetscFunctionReturn(0); 2737 } 2738 2739 #undef __FUNC__ 2740 #define __FUNC__ /*<a name=""></a>*/"MatAssemblyEnd" 2741 /*@ 2742 MatAssemblyEnd - Completes assembling the matrix. This routine should 2743 be called after MatAssemblyBegin(). 2744 2745 Collective on Mat 2746 2747 Input Parameters: 2748 + mat - the matrix 2749 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 2750 2751 Options Database Keys: 2752 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 2753 . -mat_view_info_detailed - Prints more detailed info 2754 . -mat_view - Prints matrix in ASCII format 2755 . -mat_view_matlab - Prints matrix in Matlab format 2756 . -mat_view_draw - Draws nonzero structure of matrix, using MatView() and DrawOpenX(). 2757 . -display <name> - Sets display name (default is host) 2758 - -draw_pause <sec> - Sets number of seconds to pause after display 2759 2760 Notes: 2761 MatSetValues() generally caches the values. The matrix is ready to 2762 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 2763 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 2764 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 2765 using the matrix. 2766 2767 Level: beginner 2768 2769 .seealso: MatAssemblyBegin(), MatSetValues(), DrawOpenX(), MatView(), MatAssembled() 2770 @*/ 2771 int MatAssemblyEnd(Mat mat,MatAssemblyType type) 2772 { 2773 int ierr; 2774 static int inassm = 0; 2775 2776 PetscFunctionBegin; 2777 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2778 PetscValidType(mat); 2779 MatPreallocated(mat); 2780 2781 inassm++; 2782 MatAssemblyEnd_InUse++; 2783 if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */ 2784 ierr = PLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 2785 if (mat->ops->assemblyend) { 2786 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 2787 } 2788 ierr = PLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 2789 } else { 2790 if (mat->ops->assemblyend) { 2791 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 2792 } 2793 } 2794 2795 /* Flush assembly is not a true assembly */ 2796 if (type != MAT_FLUSH_ASSEMBLY) { 2797 mat->assembled = PETSC_TRUE; mat->num_ass++; 2798 } 2799 mat->insertmode = NOT_SET_VALUES; 2800 MatAssemblyEnd_InUse--; 2801 2802 if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) { 2803 ierr = MatView_Private(mat);CHKERRQ(ierr); 2804 } 2805 inassm--; 2806 PetscFunctionReturn(0); 2807 } 2808 2809 2810 #undef __FUNC__ 2811 #define __FUNC__ /*<a name=""></a>*/"MatCompress" 2812 /*@ 2813 MatCompress - Tries to store the matrix in as little space as 2814 possible. May fail if memory is already fully used, since it 2815 tries to allocate new space. 2816 2817 Collective on Mat 2818 2819 Input Parameters: 2820 . mat - the matrix 2821 2822 Level: advanced 2823 2824 @*/ 2825 int MatCompress(Mat mat) 2826 { 2827 int ierr; 2828 2829 PetscFunctionBegin; 2830 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2831 PetscValidType(mat); 2832 MatPreallocated(mat); 2833 if (mat->ops->compress) {ierr = (*mat->ops->compress)(mat);CHKERRQ(ierr);} 2834 PetscFunctionReturn(0); 2835 } 2836 2837 #undef __FUNC__ 2838 #define __FUNC__ /*<a name=""></a>*/"MatSetOption" 2839 /*@ 2840 MatSetOption - Sets a parameter option for a matrix. Some options 2841 may be specific to certain storage formats. Some options 2842 determine how values will be inserted (or added). Sorted, 2843 row-oriented input will generally assemble the fastest. The default 2844 is row-oriented, nonsorted input. 2845 2846 Collective on Mat 2847 2848 Input Parameters: 2849 + mat - the matrix 2850 - option - the option, one of those listed below (and possibly others), 2851 e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR 2852 2853 Options Describing Matrix Structure: 2854 + MAT_SYMMETRIC - symmetric in terms of both structure and value 2855 - MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 2856 2857 Options For Use with MatSetValues(): 2858 Insert a logically dense subblock, which can be 2859 + MAT_ROW_ORIENTED - row-oriented 2860 . MAT_COLUMN_ORIENTED - column-oriented 2861 . MAT_ROWS_SORTED - sorted by row 2862 . MAT_ROWS_UNSORTED - not sorted by row 2863 . MAT_COLUMNS_SORTED - sorted by column 2864 - MAT_COLUMNS_UNSORTED - not sorted by column 2865 2866 Not these options reflect the data you pass in with MatSetValues(); it has 2867 nothing to do with how the data is stored internally in the matrix 2868 data structure. 2869 2870 When (re)assembling a matrix, we can restrict the input for 2871 efficiency/debugging purposes. These options include 2872 + MAT_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be 2873 allowed if they generate a new nonzero 2874 . MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed 2875 . MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if 2876 they generate a nonzero in a new diagonal (for block diagonal format only) 2877 . MAT_YES_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 2878 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 2879 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 2880 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 2881 2882 Notes: 2883 Some options are relevant only for particular matrix types and 2884 are thus ignored by others. Other options are not supported by 2885 certain matrix types and will generate an error message if set. 2886 2887 If using a Fortran 77 module to compute a matrix, one may need to 2888 use the column-oriented option (or convert to the row-oriented 2889 format). 2890 2891 MAT_NO_NEW_NONZERO_LOCATIONS indicates that any add or insertion 2892 that would generate a new entry in the nonzero structure is instead 2893 ignored. Thus, if memory has not alredy been allocated for this particular 2894 data, then the insertion is ignored. For dense matrices, in which 2895 the entire array is allocated, no entries are ever ignored. 2896 2897 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 2898 that would generate a new entry in the nonzero structure instead produces 2899 an error. (Currently supported for AIJ and BAIJ formats only.) 2900 This is a useful flag when using SAME_NONZERO_PATTERN in calling 2901 SLESSetOperators() to ensure that the nonzero pattern truely does 2902 remain unchanged. 2903 2904 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 2905 that would generate a new entry that has not been preallocated will 2906 instead produce an error. (Currently supported for AIJ and BAIJ formats 2907 only.) This is a useful flag when debugging matrix memory preallocation. 2908 2909 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 2910 other processors should be dropped, rather than stashed. 2911 This is useful if you know that the "owning" processor is also 2912 always generating the correct matrix entries, so that PETSc need 2913 not transfer duplicate entries generated on another processor. 2914 2915 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 2916 searches during matrix assembly. When this flag is set, the hash table 2917 is created during the first Matrix Assembly. This hash table is 2918 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 2919 to improve the searching of indices. MAT_NO_NEW_NONZERO_LOCATIONS flag 2920 should be used with MAT_USE_HASH_TABLE flag. This option is currently 2921 supported by MATMPIBAIJ format only. 2922 2923 MAT_KEEP_ZEROED_ROWS indicates when MatZeroRows() is called the zeroed entries 2924 are kept in the nonzero structure 2925 2926 MAT_IGNORE_ZERO_ENTRIES - when using ADD_VALUES for AIJ matrices this will stop 2927 zero values from creating a zero location in the matrix 2928 2929 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 2930 ROWBS matrix types 2931 2932 MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works 2933 with AIJ and ROWBS matrix types 2934 2935 Level: intermediate 2936 2937 Concepts: matrices^setting options 2938 2939 @*/ 2940 int MatSetOption(Mat mat,MatOption op) 2941 { 2942 int ierr; 2943 2944 PetscFunctionBegin; 2945 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2946 PetscValidType(mat); 2947 MatPreallocated(mat); 2948 if (mat->ops->setoption) {ierr = (*mat->ops->setoption)(mat,op);CHKERRQ(ierr);} 2949 PetscFunctionReturn(0); 2950 } 2951 2952 #undef __FUNC__ 2953 #define __FUNC__ /*<a name=""></a>*/"MatZeroEntries" 2954 /*@ 2955 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 2956 this routine retains the old nonzero structure. 2957 2958 Collective on Mat 2959 2960 Input Parameters: 2961 . mat - the matrix 2962 2963 Level: intermediate 2964 2965 Concepts: matrices^zeroing 2966 2967 .seealso: MatZeroRows() 2968 @*/ 2969 int MatZeroEntries(Mat mat) 2970 { 2971 int ierr; 2972 2973 PetscFunctionBegin; 2974 PetscValidHeaderSpecific(mat,MAT_COOKIE); 2975 PetscValidType(mat); 2976 MatPreallocated(mat); 2977 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 2978 if (!mat->ops->zeroentries) SETERRQ(PETSC_ERR_SUP,""); 2979 2980 ierr = PLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 2981 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 2982 ierr = PLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 2983 PetscFunctionReturn(0); 2984 } 2985 2986 #undef __FUNC__ 2987 #define __FUNC__ /*<a name=""></a>*/"MatZeroRows" 2988 /*@C 2989 MatZeroRows - Zeros all entries (except possibly the main diagonal) 2990 of a set of rows of a matrix. 2991 2992 Collective on Mat 2993 2994 Input Parameters: 2995 + mat - the matrix 2996 . is - index set of rows to remove 2997 - diag - pointer to value put in all diagonals of eliminated rows. 2998 Note that diag is not a pointer to an array, but merely a 2999 pointer to a single value. 3000 3001 Notes: 3002 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 3003 but does not release memory. For the dense and block diagonal 3004 formats this does not alter the nonzero structure. 3005 3006 If the option MatSetOption(mat,MAT_KEEP_ZEROED_ROWS) the nonzero structure 3007 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 3008 merely zeroed. 3009 3010 The user can set a value in the diagonal entry (or for the AIJ and 3011 row formats can optionally remove the main diagonal entry from the 3012 nonzero structure as well, by passing a null pointer (PETSC_NULL 3013 in C or PETSC_NULL_SCALAR in Fortran) as the final argument). 3014 3015 For the parallel case, all processes that share the matrix (i.e., 3016 those in the communicator used for matrix creation) MUST call this 3017 routine, regardless of whether any rows being zeroed are owned by 3018 them. 3019 3020 3021 Level: intermediate 3022 3023 Concepts: matrices^zeroing rows 3024 3025 .seealso: MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 3026 @*/ 3027 int MatZeroRows(Mat mat,IS is,Scalar *diag) 3028 { 3029 int ierr; 3030 3031 PetscFunctionBegin; 3032 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3033 PetscValidType(mat); 3034 MatPreallocated(mat); 3035 PetscValidHeaderSpecific(is,IS_COOKIE); 3036 if (diag) PetscValidScalarPointer(diag); 3037 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3038 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3039 if (!mat->ops->zerorows) SETERRQ(PETSC_ERR_SUP,""); 3040 3041 ierr = (*mat->ops->zerorows)(mat,is,diag);CHKERRQ(ierr); 3042 ierr = MatView_Private(mat);CHKERRQ(ierr); 3043 PetscFunctionReturn(0); 3044 } 3045 3046 #undef __FUNC__ 3047 #define __FUNC__ /*<a name=""></a>*/"MatZeroRowsLocal" 3048 /*@C 3049 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 3050 of a set of rows of a matrix; using local numbering of rows. 3051 3052 Collective on Mat 3053 3054 Input Parameters: 3055 + mat - the matrix 3056 . is - index set of rows to remove 3057 - diag - pointer to value put in all diagonals of eliminated rows. 3058 Note that diag is not a pointer to an array, but merely a 3059 pointer to a single value. 3060 3061 Notes: 3062 Before calling MatZeroRowsLocal(), the user must first set the 3063 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 3064 3065 For the AIJ matrix formats this removes the old nonzero structure, 3066 but does not release memory. For the dense and block diagonal 3067 formats this does not alter the nonzero structure. 3068 3069 The user can set a value in the diagonal entry (or for the AIJ and 3070 row formats can optionally remove the main diagonal entry from the 3071 nonzero structure as well, by passing a null pointer (PETSC_NULL 3072 in C or PETSC_NULL_SCALAR in Fortran) as the final argument). 3073 3074 Level: intermediate 3075 3076 Concepts: matrices^zeroing 3077 3078 .seealso: MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 3079 @*/ 3080 int MatZeroRowsLocal(Mat mat,IS is,Scalar *diag) 3081 { 3082 int ierr; 3083 IS newis; 3084 3085 PetscFunctionBegin; 3086 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3087 PetscValidType(mat); 3088 MatPreallocated(mat); 3089 PetscValidHeaderSpecific(is,IS_COOKIE); 3090 if (diag) PetscValidScalarPointer(diag); 3091 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3092 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3093 3094 if (mat->ops->zerorowslocal) { 3095 ierr = (*mat->ops->zerorowslocal)(mat,is,diag);CHKERRQ(ierr); 3096 } else { 3097 if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 3098 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 3099 ierr = (*mat->ops->zerorows)(mat,newis,diag);CHKERRQ(ierr); 3100 ierr = ISDestroy(newis);CHKERRQ(ierr); 3101 } 3102 PetscFunctionReturn(0); 3103 } 3104 3105 #undef __FUNC__ 3106 #define __FUNC__ /*<a name=""></a>*/"MatGetSize" 3107 /*@ 3108 MatGetSize - Returns the numbers of rows and columns in a matrix. 3109 3110 Not Collective 3111 3112 Input Parameter: 3113 . mat - the matrix 3114 3115 Output Parameters: 3116 + m - the number of global rows 3117 - n - the number of global columns 3118 3119 Level: beginner 3120 3121 Concepts: matrices^size 3122 3123 .seealso: MatGetLocalSize() 3124 @*/ 3125 int MatGetSize(Mat mat,int *m,int* n) 3126 { 3127 PetscFunctionBegin; 3128 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3129 if (m) *m = mat->M; 3130 if (n) *n = mat->N; 3131 PetscFunctionReturn(0); 3132 } 3133 3134 #undef __FUNC__ 3135 #define __FUNC__ /*<a name=""></a>*/"MatGetLocalSize" 3136 /*@ 3137 MatGetLocalSize - Returns the number of rows and columns in a matrix 3138 stored locally. This information may be implementation dependent, so 3139 use with care. 3140 3141 Not Collective 3142 3143 Input Parameters: 3144 . mat - the matrix 3145 3146 Output Parameters: 3147 + m - the number of local rows 3148 - n - the number of local columns 3149 3150 Level: beginner 3151 3152 Concepts: matrices^local size 3153 3154 .seealso: MatGetSize() 3155 @*/ 3156 int MatGetLocalSize(Mat mat,int *m,int* n) 3157 { 3158 PetscFunctionBegin; 3159 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3160 if (m) *m = mat->m; 3161 if (n) *n = mat->n; 3162 PetscFunctionReturn(0); 3163 } 3164 3165 #undef __FUNC__ 3166 #define __FUNC__ /*<a name=""></a>*/"MatGetOwnershipRange" 3167 /*@ 3168 MatGetOwnershipRange - Returns the range of matrix rows owned by 3169 this processor, assuming that the matrix is laid out with the first 3170 n1 rows on the first processor, the next n2 rows on the second, etc. 3171 For certain parallel layouts this range may not be well defined. 3172 3173 Not Collective 3174 3175 Input Parameters: 3176 . mat - the matrix 3177 3178 Output Parameters: 3179 + m - the global index of the first local row 3180 - n - one more than the global index of the last local row 3181 3182 Level: beginner 3183 3184 Concepts: matrices^row ownership 3185 @*/ 3186 int MatGetOwnershipRange(Mat mat,int *m,int* n) 3187 { 3188 int ierr; 3189 3190 PetscFunctionBegin; 3191 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3192 PetscValidType(mat); 3193 MatPreallocated(mat); 3194 if (m) PetscValidIntPointer(m); 3195 if (n) PetscValidIntPointer(n); 3196 if (!mat->ops->getownershiprange) SETERRQ(PETSC_ERR_SUP,""); 3197 ierr = (*mat->ops->getownershiprange)(mat,m,n);CHKERRQ(ierr); 3198 PetscFunctionReturn(0); 3199 } 3200 3201 #undef __FUNC__ 3202 #define __FUNC__ /*<a name=""></a>*/"MatILUFactorSymbolic" 3203 /*@ 3204 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 3205 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 3206 to complete the factorization. 3207 3208 Collective on Mat 3209 3210 Input Parameters: 3211 + mat - the matrix 3212 . row - row permutation 3213 . column - column permutation 3214 - info - structure containing 3215 $ levels - number of levels of fill. 3216 $ expected fill - as ratio of original fill. 3217 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 3218 missing diagonal entries) 3219 3220 Output Parameters: 3221 . fact - new matrix that has been symbolically factored 3222 3223 Notes: 3224 See the users manual for additional information about 3225 choosing the fill factor for better efficiency. 3226 3227 Most users should employ the simplified SLES interface for linear solvers 3228 instead of working directly with matrix algebra routines such as this. 3229 See, e.g., SLESCreate(). 3230 3231 Level: developer 3232 3233 Concepts: matrices^symbolic LU factorization 3234 Concepts: matrices^factorization 3235 Concepts: LU^symbolic factorization 3236 3237 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 3238 MatGetOrdering() 3239 3240 @*/ 3241 int MatILUFactorSymbolic(Mat mat,IS row,IS col,MatILUInfo *info,Mat *fact) 3242 { 3243 int ierr; 3244 3245 PetscFunctionBegin; 3246 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3247 PetscValidType(mat); 3248 MatPreallocated(mat); 3249 PetscValidPointer(fact); 3250 if (info && info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %d",info->levels); 3251 if (info && info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",info->fill); 3252 if (!mat->ops->ilufactorsymbolic) SETERRQ(PETSC_ERR_SUP,"Only MatCreateMPIRowbs() matrices support parallel ILU"); 3253 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3254 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3255 3256 ierr = PLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 3257 ierr = (*mat->ops->ilufactorsymbolic)(mat,row,col,info,fact);CHKERRQ(ierr); 3258 ierr = PLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 3259 PetscFunctionReturn(0); 3260 } 3261 3262 #undef __FUNC__ 3263 #define __FUNC__ /*<a name=""></a>*/"MatIncompleteCholeskyFactorSymbolic" 3264 /*@ 3265 MatIncompleteCholeskyFactorSymbolic - Performs symbolic incomplete 3266 Cholesky factorization for a symmetric matrix. Use 3267 MatCholeskyFactorNumeric() to complete the factorization. 3268 3269 Collective on Mat 3270 3271 Input Parameters: 3272 + mat - the matrix 3273 . perm - row and column permutation 3274 . fill - levels of fill 3275 - f - expected fill as ratio of original fill 3276 3277 Output Parameter: 3278 . fact - the factored matrix 3279 3280 Notes: 3281 Currently only no-fill factorization is supported. 3282 3283 Most users should employ the simplified SLES interface for linear solvers 3284 instead of working directly with matrix algebra routines such as this. 3285 See, e.g., SLESCreate(). 3286 3287 Level: developer 3288 3289 Concepts: matrices^symbolic incomplete Cholesky factorization 3290 Concepts: matrices^factorization 3291 Concepts: Cholsky^symbolic factorization 3292 3293 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor() 3294 @*/ 3295 int MatIncompleteCholeskyFactorSymbolic(Mat mat,IS perm,PetscReal f,int fill,Mat *fact) 3296 { 3297 int ierr; 3298 3299 PetscFunctionBegin; 3300 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3301 PetscValidType(mat); 3302 MatPreallocated(mat); 3303 PetscValidPointer(fact); 3304 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3305 if (fill < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Fill negative %d",fill); 3306 if (f < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %g",f); 3307 if (!mat->ops->incompletecholeskyfactorsymbolic) SETERRQ(PETSC_ERR_SUP,"Currently only MatCreateMPIRowbs() matrices support ICC in parallel"); 3308 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3309 3310 ierr = PLogEventBegin(MAT_IncompleteCholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 3311 ierr = (*mat->ops->incompletecholeskyfactorsymbolic)(mat,perm,f,fill,fact);CHKERRQ(ierr); 3312 ierr = PLogEventEnd(MAT_IncompleteCholeskyFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 3313 PetscFunctionReturn(0); 3314 } 3315 3316 #undef __FUNC__ 3317 #define __FUNC__ /*<a name=""></a>*/"MatGetArray" 3318 /*@C 3319 MatGetArray - Returns a pointer to the element values in the matrix. 3320 The result of this routine is dependent on the underlying matrix data 3321 structure, and may not even work for certain matrix types. You MUST 3322 call MatRestoreArray() when you no longer need to access the array. 3323 3324 Not Collective 3325 3326 Input Parameter: 3327 . mat - the matrix 3328 3329 Output Parameter: 3330 . v - the location of the values 3331 3332 Currently returns an array only for the dense formats, giving access to 3333 the local portion of the matrix in the usual Fortran column-oriented format. 3334 3335 Fortran Note: 3336 This routine is used differently from Fortran, e.g., 3337 .vb 3338 Mat mat 3339 Scalar mat_array(1) 3340 PetscOffset i_mat 3341 int ierr 3342 call MatGetArray(mat,mat_array,i_mat,ierr) 3343 3344 C Access first local entry in matrix; note that array is 3345 C treated as one dimensional 3346 value = mat_array(i_mat + 1) 3347 3348 [... other code ...] 3349 call MatRestoreArray(mat,mat_array,i_mat,ierr) 3350 .ve 3351 3352 See the Fortran chapter of the users manual and 3353 petsc/src/mat/examples/tests for details. 3354 3355 Level: advanced 3356 3357 Concepts: matrices^access array 3358 3359 .seealso: MatRestoreArray(), MatGetArrayF90() 3360 @*/ 3361 int MatGetArray(Mat mat,Scalar **v) 3362 { 3363 int ierr; 3364 3365 PetscFunctionBegin; 3366 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3367 PetscValidType(mat); 3368 MatPreallocated(mat); 3369 PetscValidPointer(v); 3370 if (!mat->ops->getarray) SETERRQ(PETSC_ERR_SUP,""); 3371 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 3372 PetscFunctionReturn(0); 3373 } 3374 3375 #undef __FUNC__ 3376 #define __FUNC__ /*<a name=""></a>*/"MatRestoreArray" 3377 /*@C 3378 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 3379 3380 Not Collective 3381 3382 Input Parameter: 3383 + mat - the matrix 3384 - v - the location of the values 3385 3386 Fortran Note: 3387 This routine is used differently from Fortran, e.g., 3388 .vb 3389 Mat mat 3390 Scalar mat_array(1) 3391 PetscOffset i_mat 3392 int ierr 3393 call MatGetArray(mat,mat_array,i_mat,ierr) 3394 3395 C Access first local entry in matrix; note that array is 3396 C treated as one dimensional 3397 value = mat_array(i_mat + 1) 3398 3399 [... other code ...] 3400 call MatRestoreArray(mat,mat_array,i_mat,ierr) 3401 .ve 3402 3403 See the Fortran chapter of the users manual and 3404 petsc/src/mat/examples/tests for details 3405 3406 Level: advanced 3407 3408 .seealso: MatGetArray(), MatRestoreArrayF90() 3409 @*/ 3410 int MatRestoreArray(Mat mat,Scalar **v) 3411 { 3412 int ierr; 3413 3414 PetscFunctionBegin; 3415 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3416 PetscValidType(mat); 3417 MatPreallocated(mat); 3418 PetscValidPointer(v); 3419 if (!mat->ops->restorearray) SETERRQ(PETSC_ERR_SUP,""); 3420 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 3421 PetscFunctionReturn(0); 3422 } 3423 3424 #undef __FUNC__ 3425 #define __FUNC__ /*<a name=""></a>*/"MatGetSubMatrices" 3426 /*@C 3427 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 3428 points to an array of valid matrices, they may be reused to store the new 3429 submatrices. 3430 3431 Collective on Mat 3432 3433 Input Parameters: 3434 + mat - the matrix 3435 . n - the number of submatrixes to be extracted (on this processor, may be zero) 3436 . irow, icol - index sets of rows and columns to extract 3437 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 3438 3439 Output Parameter: 3440 . submat - the array of submatrices 3441 3442 Notes: 3443 MatGetSubMatrices() can extract only sequential submatrices 3444 (from both sequential and parallel matrices). Use MatGetSubMatrix() 3445 to extract a parallel submatrix. 3446 3447 When extracting submatrices from a parallel matrix, each processor can 3448 form a different submatrix by setting the rows and columns of its 3449 individual index sets according to the local submatrix desired. 3450 3451 When finished using the submatrices, the user should destroy 3452 them with MatDestroySubMatrices(). 3453 3454 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 3455 original matrix has not changed from that last call to MatGetSubMatrices(). 3456 3457 Fortran Note: 3458 The Fortran interface is slightly different from that given below; it 3459 requires one to pass in as submat a Mat (integer) array of size at least m. 3460 3461 Level: advanced 3462 3463 Concepts: matrices^accessing submatrices 3464 Concepts: submatrices 3465 3466 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal() 3467 @*/ 3468 int MatGetSubMatrices(Mat mat,int n,IS *irow,IS *icol,MatReuse scall,Mat **submat) 3469 { 3470 int ierr; 3471 3472 PetscFunctionBegin; 3473 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3474 PetscValidType(mat); 3475 MatPreallocated(mat); 3476 if (!mat->ops->getsubmatrices) SETERRQ(PETSC_ERR_SUP,""); 3477 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3478 3479 ierr = PLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 3480 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 3481 ierr = PLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 3482 3483 PetscFunctionReturn(0); 3484 } 3485 3486 #undef __FUNC__ 3487 #define __FUNC__ /*<a name=""></a>*/"MatDestroyMatrices" 3488 /*@C 3489 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 3490 3491 Collective on Mat 3492 3493 Input Parameters: 3494 + n - the number of local matrices 3495 - mat - the matrices 3496 3497 Level: advanced 3498 3499 .seealso: MatGetSubMatrices() 3500 @*/ 3501 int MatDestroyMatrices(int n,Mat **mat) 3502 { 3503 int ierr,i; 3504 3505 PetscFunctionBegin; 3506 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %d",n); 3507 PetscValidPointer(mat); 3508 for (i=0; i<n; i++) { 3509 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 3510 } 3511 /* memory is allocated even if n = 0 */ 3512 ierr = PetscFree(*mat);CHKERRQ(ierr); 3513 PetscFunctionReturn(0); 3514 } 3515 3516 #undef __FUNC__ 3517 #define __FUNC__ /*<a name=""></a>*/"MatIncreaseOverlap" 3518 /*@ 3519 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 3520 replaces the index sets by larger ones that represent submatrices with 3521 additional overlap. 3522 3523 Collective on Mat 3524 3525 Input Parameters: 3526 + mat - the matrix 3527 . n - the number of index sets 3528 . is - the array of pointers to index sets 3529 - ov - the additional overlap requested 3530 3531 Level: developer 3532 3533 Concepts: overlap 3534 Concepts: ASM^computing overlap 3535 3536 .seealso: MatGetSubMatrices() 3537 @*/ 3538 int MatIncreaseOverlap(Mat mat,int n,IS *is,int ov) 3539 { 3540 int ierr; 3541 3542 PetscFunctionBegin; 3543 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3544 PetscValidType(mat); 3545 MatPreallocated(mat); 3546 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 3547 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 3548 3549 if (!ov) PetscFunctionReturn(0); 3550 if (!mat->ops->increaseoverlap) SETERRQ(PETSC_ERR_SUP,""); 3551 ierr = PLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 3552 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 3553 ierr = PLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 3554 PetscFunctionReturn(0); 3555 } 3556 3557 #undef __FUNC__ 3558 #define __FUNC__ /*<a name=""></a>*/"MatPrintHelp" 3559 /*@ 3560 MatPrintHelp - Prints all the options for the matrix. 3561 3562 Collective on Mat 3563 3564 Input Parameter: 3565 . mat - the matrix 3566 3567 Options Database Keys: 3568 + -help - Prints matrix options 3569 - -h - Prints matrix options 3570 3571 Level: developer 3572 3573 .seealso: MatCreate(), MatCreateXXX() 3574 @*/ 3575 int MatPrintHelp(Mat mat) 3576 { 3577 static PetscTruth called = PETSC_FALSE; 3578 int ierr; 3579 MPI_Comm comm; 3580 3581 PetscFunctionBegin; 3582 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3583 PetscValidType(mat); 3584 MatPreallocated(mat); 3585 3586 comm = mat->comm; 3587 if (!called) { 3588 ierr = (*PetscHelpPrintf)(comm,"General matrix options:\n");CHKERRQ(ierr); 3589 ierr = (*PetscHelpPrintf)(comm," -mat_view_info: view basic matrix info during MatAssemblyEnd()\n");CHKERRQ(ierr); 3590 ierr = (*PetscHelpPrintf)(comm," -mat_view_info_detailed: view detailed matrix info during MatAssemblyEnd()\n");CHKERRQ(ierr); 3591 ierr = (*PetscHelpPrintf)(comm," -mat_view_draw: draw nonzero matrix structure during MatAssemblyEnd()\n");CHKERRQ(ierr); 3592 ierr = (*PetscHelpPrintf)(comm," -draw_pause <sec>: set seconds of display pause\n");CHKERRQ(ierr); 3593 ierr = (*PetscHelpPrintf)(comm," -display <name>: set alternate display\n");CHKERRQ(ierr); 3594 called = PETSC_TRUE; 3595 } 3596 if (mat->ops->printhelp) { 3597 ierr = (*mat->ops->printhelp)(mat);CHKERRQ(ierr); 3598 } 3599 PetscFunctionReturn(0); 3600 } 3601 3602 #undef __FUNC__ 3603 #define __FUNC__ /*<a name=""></a>*/"MatGetBlockSize" 3604 /*@ 3605 MatGetBlockSize - Returns the matrix block size; useful especially for the 3606 block row and block diagonal formats. 3607 3608 Not Collective 3609 3610 Input Parameter: 3611 . mat - the matrix 3612 3613 Output Parameter: 3614 . bs - block size 3615 3616 Notes: 3617 Block diagonal formats are MATSEQBDIAG, MATMPIBDIAG. 3618 Block row formats are MATSEQBAIJ, MATMPIBAIJ 3619 3620 Level: intermediate 3621 3622 Concepts: matrices^block size 3623 3624 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatCreateSeqBDiag(), MatCreateMPIBDiag() 3625 @*/ 3626 int MatGetBlockSize(Mat mat,int *bs) 3627 { 3628 int ierr; 3629 3630 PetscFunctionBegin; 3631 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3632 PetscValidType(mat); 3633 MatPreallocated(mat); 3634 PetscValidIntPointer(bs); 3635 if (!mat->ops->getblocksize) SETERRQ(PETSC_ERR_SUP,""); 3636 ierr = (*mat->ops->getblocksize)(mat,bs);CHKERRQ(ierr); 3637 PetscFunctionReturn(0); 3638 } 3639 3640 #undef __FUNC__ 3641 #define __FUNC__ /*<a name=""></a>*/"MatGetRowIJ" 3642 /*@C 3643 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 3644 3645 Collective on Mat 3646 3647 Input Parameters: 3648 + mat - the matrix 3649 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 3650 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 3651 symmetrized 3652 3653 Output Parameters: 3654 + n - number of rows in the (possibly compressed) matrix 3655 . ia - the row pointers 3656 . ja - the column indices 3657 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 3658 3659 Level: developer 3660 3661 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 3662 @*/ 3663 int MatGetRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done) 3664 { 3665 int ierr; 3666 3667 PetscFunctionBegin; 3668 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3669 PetscValidType(mat); 3670 MatPreallocated(mat); 3671 if (ia) PetscValidIntPointer(ia); 3672 if (ja) PetscValidIntPointer(ja); 3673 PetscValidIntPointer(done); 3674 if (!mat->ops->getrowij) *done = PETSC_FALSE; 3675 else { 3676 *done = PETSC_TRUE; 3677 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 3678 } 3679 PetscFunctionReturn(0); 3680 } 3681 3682 #undef __FUNC__ 3683 #define __FUNC__ /*<a name=""></a>*/"MatGetColumnIJ" 3684 /*@C 3685 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 3686 3687 Collective on Mat 3688 3689 Input Parameters: 3690 + mat - the matrix 3691 . shift - 1 or zero indicating we want the indices starting at 0 or 1 3692 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 3693 symmetrized 3694 3695 Output Parameters: 3696 + n - number of columns in the (possibly compressed) matrix 3697 . ia - the column pointers 3698 . ja - the row indices 3699 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 3700 3701 Level: developer 3702 3703 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 3704 @*/ 3705 int MatGetColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done) 3706 { 3707 int ierr; 3708 3709 PetscFunctionBegin; 3710 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3711 PetscValidType(mat); 3712 MatPreallocated(mat); 3713 if (ia) PetscValidIntPointer(ia); 3714 if (ja) PetscValidIntPointer(ja); 3715 PetscValidIntPointer(done); 3716 3717 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 3718 else { 3719 *done = PETSC_TRUE; 3720 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 3721 } 3722 PetscFunctionReturn(0); 3723 } 3724 3725 #undef __FUNC__ 3726 #define __FUNC__ /*<a name=""></a>*/"MatRestoreRowIJ" 3727 /*@C 3728 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 3729 MatGetRowIJ(). 3730 3731 Collective on Mat 3732 3733 Input Parameters: 3734 + mat - the matrix 3735 . shift - 1 or zero indicating we want the indices starting at 0 or 1 3736 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 3737 symmetrized 3738 3739 Output Parameters: 3740 + n - size of (possibly compressed) matrix 3741 . ia - the row pointers 3742 . ja - the column indices 3743 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 3744 3745 Level: developer 3746 3747 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 3748 @*/ 3749 int MatRestoreRowIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done) 3750 { 3751 int ierr; 3752 3753 PetscFunctionBegin; 3754 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3755 PetscValidType(mat); 3756 MatPreallocated(mat); 3757 if (ia) PetscValidIntPointer(ia); 3758 if (ja) PetscValidIntPointer(ja); 3759 PetscValidIntPointer(done); 3760 3761 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 3762 else { 3763 *done = PETSC_TRUE; 3764 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 3765 } 3766 PetscFunctionReturn(0); 3767 } 3768 3769 #undef __FUNC__ 3770 #define __FUNC__ /*<a name=""></a>*/"MatRestoreColumnIJ" 3771 /*@C 3772 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 3773 MatGetColumnIJ(). 3774 3775 Collective on Mat 3776 3777 Input Parameters: 3778 + mat - the matrix 3779 . shift - 1 or zero indicating we want the indices starting at 0 or 1 3780 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 3781 symmetrized 3782 3783 Output Parameters: 3784 + n - size of (possibly compressed) matrix 3785 . ia - the column pointers 3786 . ja - the row indices 3787 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 3788 3789 Level: developer 3790 3791 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 3792 @*/ 3793 int MatRestoreColumnIJ(Mat mat,int shift,PetscTruth symmetric,int *n,int **ia,int** ja,PetscTruth *done) 3794 { 3795 int ierr; 3796 3797 PetscFunctionBegin; 3798 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3799 PetscValidType(mat); 3800 MatPreallocated(mat); 3801 if (ia) PetscValidIntPointer(ia); 3802 if (ja) PetscValidIntPointer(ja); 3803 PetscValidIntPointer(done); 3804 3805 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 3806 else { 3807 *done = PETSC_TRUE; 3808 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,n,ia,ja,done);CHKERRQ(ierr); 3809 } 3810 PetscFunctionReturn(0); 3811 } 3812 3813 #undef __FUNC__ 3814 #define __FUNC__ /*<a name=""></a>*/"MatColoringPatch" 3815 /*@C 3816 MatColoringPatch -Used inside matrix coloring routines that 3817 use MatGetRowIJ() and/or MatGetColumnIJ(). 3818 3819 Collective on Mat 3820 3821 Input Parameters: 3822 + mat - the matrix 3823 . n - number of colors 3824 - colorarray - array indicating color for each column 3825 3826 Output Parameters: 3827 . iscoloring - coloring generated using colorarray information 3828 3829 Level: developer 3830 3831 .seealso: MatGetRowIJ(), MatGetColumnIJ() 3832 3833 @*/ 3834 int MatColoringPatch(Mat mat,int n,int *colorarray,ISColoring *iscoloring) 3835 { 3836 int ierr; 3837 3838 PetscFunctionBegin; 3839 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3840 PetscValidType(mat); 3841 MatPreallocated(mat); 3842 PetscValidIntPointer(colorarray); 3843 3844 if (!mat->ops->coloringpatch) {SETERRQ(PETSC_ERR_SUP,"");} 3845 else { 3846 ierr = (*mat->ops->coloringpatch)(mat,n,colorarray,iscoloring);CHKERRQ(ierr); 3847 } 3848 PetscFunctionReturn(0); 3849 } 3850 3851 3852 #undef __FUNC__ 3853 #define __FUNC__ /*<a name=""></a>*/"MatSetUnfactored" 3854 /*@ 3855 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 3856 3857 Collective on Mat 3858 3859 Input Parameter: 3860 . mat - the factored matrix to be reset 3861 3862 Notes: 3863 This routine should be used only with factored matrices formed by in-place 3864 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 3865 format). This option can save memory, for example, when solving nonlinear 3866 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 3867 ILU(0) preconditioner. 3868 3869 Note that one can specify in-place ILU(0) factorization by calling 3870 .vb 3871 PCType(pc,PCILU); 3872 PCILUSeUseInPlace(pc); 3873 .ve 3874 or by using the options -pc_type ilu -pc_ilu_in_place 3875 3876 In-place factorization ILU(0) can also be used as a local 3877 solver for the blocks within the block Jacobi or additive Schwarz 3878 methods (runtime option: -sub_pc_ilu_in_place). See the discussion 3879 of these preconditioners in the users manual for details on setting 3880 local solver options. 3881 3882 Most users should employ the simplified SLES interface for linear solvers 3883 instead of working directly with matrix algebra routines such as this. 3884 See, e.g., SLESCreate(). 3885 3886 Level: developer 3887 3888 .seealso: PCILUSetUseInPlace(), PCLUSetUseInPlace() 3889 3890 Concepts: matrices^unfactored 3891 3892 @*/ 3893 int MatSetUnfactored(Mat mat) 3894 { 3895 int ierr; 3896 3897 PetscFunctionBegin; 3898 PetscValidHeaderSpecific(mat,MAT_COOKIE); 3899 PetscValidType(mat); 3900 MatPreallocated(mat); 3901 mat->factor = 0; 3902 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 3903 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 3904 PetscFunctionReturn(0); 3905 } 3906 3907 /*MC 3908 MatGetArrayF90 - Accesses a matrix array from Fortran90. 3909 3910 Synopsis: 3911 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 3912 3913 Not collective 3914 3915 Input Parameter: 3916 . x - matrix 3917 3918 Output Parameters: 3919 + xx_v - the Fortran90 pointer to the array 3920 - ierr - error code 3921 3922 Example of Usage: 3923 .vb 3924 Scalar, pointer xx_v(:) 3925 .... 3926 call MatGetArrayF90(x,xx_v,ierr) 3927 a = xx_v(3) 3928 call MatRestoreArrayF90(x,xx_v,ierr) 3929 .ve 3930 3931 Notes: 3932 Not yet supported for all F90 compilers 3933 3934 Level: advanced 3935 3936 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 3937 3938 Concepts: matrices^accessing array 3939 3940 M*/ 3941 3942 /*MC 3943 MatRestoreArrayF90 - Restores a matrix array that has been 3944 accessed with MatGetArrayF90(). 3945 3946 Synopsis: 3947 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 3948 3949 Not collective 3950 3951 Input Parameters: 3952 + x - matrix 3953 - xx_v - the Fortran90 pointer to the array 3954 3955 Output Parameter: 3956 . ierr - error code 3957 3958 Example of Usage: 3959 .vb 3960 Scalar, pointer xx_v(:) 3961 .... 3962 call MatGetArrayF90(x,xx_v,ierr) 3963 a = xx_v(3) 3964 call MatRestoreArrayF90(x,xx_v,ierr) 3965 .ve 3966 3967 Notes: 3968 Not yet supported for all F90 compilers 3969 3970 Level: advanced 3971 3972 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 3973 3974 M*/ 3975 3976 3977 #undef __FUNC__ 3978 #define __FUNC__ /*<a name=""></a>*/"MatGetSubMatrix" 3979 /*@ 3980 MatGetSubMatrix - Gets a single submatrix on the same number of processors 3981 as the original matrix. 3982 3983 Collective on Mat 3984 3985 Input Parameters: 3986 + mat - the original matrix 3987 . isrow - rows this processor should obtain 3988 . iscol - columns for all processors you wish to keep 3989 . csize - number of columns "local" to this processor (does nothing for sequential 3990 matrices). This should match the result from VecGetLocalSize(x,...) if you 3991 plan to use the matrix in a A*x; alternatively, you can use PETSC_DECIDE 3992 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 3993 3994 Output Parameter: 3995 . newmat - the new submatrix, of the same type as the old 3996 3997 Level: advanced 3998 3999 Notes: the iscol argument MST be the same on each processor 4000 4001 Concepts: matrices^submatrices 4002 4003 .seealso: MatGetSubMatrices() 4004 @*/ 4005 int MatGetSubMatrix(Mat mat,IS isrow,IS iscol,int csize,MatReuse cll,Mat *newmat) 4006 { 4007 int ierr, size; 4008 Mat *local; 4009 4010 PetscFunctionBegin; 4011 PetscValidType(mat); 4012 MatPreallocated(mat); 4013 ierr = MPI_Comm_size(mat->comm,&size);CHKERRQ(ierr); 4014 4015 /* if original matrix is on just one processor then use submatrix generated */ 4016 if (!mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 4017 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 4018 PetscFunctionReturn(0); 4019 } else if (!mat->ops->getsubmatrix && size == 1) { 4020 ierr = MatGetSubMatrices(mat,1,&isrow,&iscol,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 4021 *newmat = *local; 4022 ierr = PetscFree(local);CHKERRQ(ierr); 4023 PetscFunctionReturn(0); 4024 } 4025 4026 if (!mat->ops->getsubmatrix) SETERRQ(PETSC_ERR_SUP,"Not currently implemented"); 4027 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscol,csize,cll,newmat);CHKERRQ(ierr); 4028 PetscFunctionReturn(0); 4029 } 4030 4031 #undef __FUNC__ 4032 #define __FUNC__ /*<a name=""></a>*/"MatGetMaps" 4033 /*@C 4034 MatGetMaps - Returns the maps associated with the matrix. 4035 4036 Not Collective 4037 4038 Input Parameter: 4039 . mat - the matrix 4040 4041 Output Parameters: 4042 + rmap - the row (right) map 4043 - cmap - the column (left) map 4044 4045 Level: developer 4046 4047 Concepts: maps^getting from matrix 4048 4049 @*/ 4050 int MatGetMaps(Mat mat,Map *rmap,Map *cmap) 4051 { 4052 int ierr; 4053 4054 PetscFunctionBegin; 4055 PetscValidHeaderSpecific(mat,MAT_COOKIE); 4056 PetscValidType(mat); 4057 MatPreallocated(mat); 4058 ierr = (*mat->ops->getmaps)(mat,rmap,cmap);CHKERRQ(ierr); 4059 PetscFunctionReturn(0); 4060 } 4061 4062 /* 4063 Version that works for all PETSc matrices 4064 */ 4065 #undef __FUNC__ 4066 #define __FUNC__ /*<a name=""></a>*/"MatGetMaps_Petsc" 4067 int MatGetMaps_Petsc(Mat mat,Map *rmap,Map *cmap) 4068 { 4069 PetscFunctionBegin; 4070 if (rmap) *rmap = mat->rmap; 4071 if (cmap) *cmap = mat->cmap; 4072 PetscFunctionReturn(0); 4073 } 4074 4075 #undef __FUNC__ 4076 #define __FUNC__ /*<a name=""></a>*/"MatSetStashInitialSize" 4077 /*@ 4078 MatSetStashInitialSize - sets the sizes of the matrix stash, that is 4079 used during the assembly process to store values that belong to 4080 other processors. 4081 4082 Not Collective 4083 4084 Input Parameters: 4085 + mat - the matrix 4086 . size - the initial size of the stash. 4087 - bsize - the initial size of the block-stash(if used). 4088 4089 Options Database Keys: 4090 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 4091 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 4092 4093 Level: intermediate 4094 4095 Notes: 4096 The block-stash is used for values set with VecSetValuesBlocked() while 4097 the stash is used for values set with VecSetValues() 4098 4099 Run with the option -log_info and look for output of the form 4100 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 4101 to determine the appropriate value, MM, to use for size and 4102 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 4103 to determine the value, BMM to use for bsize 4104 4105 Concepts: stash^setting matrix size 4106 Concepts: matrices^stash 4107 4108 @*/ 4109 int MatSetStashInitialSize(Mat mat,int size, int bsize) 4110 { 4111 int ierr; 4112 4113 PetscFunctionBegin; 4114 PetscValidHeaderSpecific(mat,MAT_COOKIE); 4115 PetscValidType(mat); 4116 MatPreallocated(mat); 4117 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 4118 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 4119 PetscFunctionReturn(0); 4120 } 4121 4122 #undef __FUNC__ 4123 #define __FUNC__ /*<a name=""></a>*/"MatInterpolateAdd" 4124 /*@ 4125 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 4126 the matrix 4127 4128 Collective on Mat 4129 4130 Input Parameters: 4131 + mat - the matrix 4132 . x,y - the vectors 4133 - w - where the result is stored 4134 4135 Level: intermediate 4136 4137 Notes: 4138 w may be the same vector as y. 4139 4140 This allows one to use either the restriction or interpolation (its transpose) 4141 matrix to do the interpolation 4142 4143 Concepts: interpolation 4144 4145 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 4146 4147 @*/ 4148 int MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 4149 { 4150 int M,N,ierr; 4151 4152 PetscFunctionBegin; 4153 PetscValidType(A); 4154 MatPreallocated(A); 4155 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 4156 if (N > M) { 4157 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 4158 } else { 4159 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 4160 } 4161 PetscFunctionReturn(0); 4162 } 4163 4164 #undef __FUNC__ 4165 #define __FUNC__ /*<a name=""></a>*/"MatInterpolate" 4166 /*@ 4167 MatInterpolate - y = A*x or A'*x depending on the shape of 4168 the matrix 4169 4170 Collective on Mat 4171 4172 Input Parameters: 4173 + mat - the matrix 4174 - x,y - the vectors 4175 4176 Level: intermediate 4177 4178 Notes: 4179 This allows one to use either the restriction or interpolation (its transpose) 4180 matrix to do the interpolation 4181 4182 Concepts: matrices^interpolation 4183 4184 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 4185 4186 @*/ 4187 int MatInterpolate(Mat A,Vec x,Vec y) 4188 { 4189 int M,N,ierr; 4190 4191 PetscFunctionBegin; 4192 PetscValidType(A); 4193 MatPreallocated(A); 4194 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 4195 if (N > M) { 4196 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 4197 } else { 4198 ierr = MatMult(A,x,y);CHKERRQ(ierr); 4199 } 4200 PetscFunctionReturn(0); 4201 } 4202 4203 #undef __FUNC__ 4204 #define __FUNC__ /*<a name=""></a>*/"MatRestrict" 4205 /*@ 4206 MatRestrict - y = A*x or A'*x 4207 4208 Collective on Mat 4209 4210 Input Parameters: 4211 + mat - the matrix 4212 - x,y - the vectors 4213 4214 Level: intermediate 4215 4216 Notes: 4217 This allows one to use either the restriction or interpolation (its transpose) 4218 matrix to do the restriction 4219 4220 Concepts: matrices^restriction 4221 4222 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 4223 4224 @*/ 4225 int MatRestrict(Mat A,Vec x,Vec y) 4226 { 4227 int M,N,ierr; 4228 4229 PetscFunctionBegin; 4230 PetscValidType(A); 4231 MatPreallocated(A); 4232 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 4233 if (N > M) { 4234 ierr = MatMult(A,x,y);CHKERRQ(ierr); 4235 } else { 4236 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 4237 } 4238 PetscFunctionReturn(0); 4239 } 4240 4241 #undef __FUNC__ 4242 #define __FUNC__ /*<a name=""></a>*/"MatNullSpaceAttach" 4243 /*@C 4244 MatNullSpaceAttach - attaches a null space to a matrix. 4245 This null space will be removed from the resulting vector whenever 4246 MatMult() is called 4247 4248 Collective on Mat 4249 4250 Input Parameters: 4251 + mat - the matrix 4252 - nullsp - the null space object 4253 4254 Level: developer 4255 4256 Notes: 4257 Overwrites any previous null space that may have been attached 4258 4259 Concepts: null space^attaching to matrix 4260 4261 .seealso: MatCreate(), MatNullSpaceCreate() 4262 @*/ 4263 int MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 4264 { 4265 int ierr = 0; 4266 4267 PetscFunctionBegin; 4268 PetscValidHeaderSpecific(mat,MAT_COOKIE); 4269 PetscValidType(mat); 4270 MatPreallocated(mat); 4271 PetscValidHeaderSpecific(nullsp,MATNULLSPACE_COOKIE); 4272 4273 if (mat->nullsp) { 4274 ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); 4275 } 4276 mat->nullsp = nullsp; 4277 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 4278 PetscFunctionReturn(0); 4279 } 4280 4281 #undef __FUNC__ 4282 #define __FUNC__ /*<a name=""></a>*/"MatIncompleteCholeskyFactor" 4283 /*@ 4284 MatIncompleteCholeskyFactor - Performs in-place incomplete Cholesky factorization of matrix. 4285 4286 Collective on Mat 4287 4288 Input Parameters: 4289 + mat - the matrix 4290 . row - row/column permutation 4291 . fill - expected fill factor >= 1.0 4292 - level - level of fill, for ICC(k) 4293 4294 Notes: 4295 Probably really in-place only when level of fill is zero, otherwise allocates 4296 new space to store factored matrix and deletes previous memory. 4297 4298 Most users should employ the simplified SLES interface for linear solvers 4299 instead of working directly with matrix algebra routines such as this. 4300 See, e.g., SLESCreate(). 4301 4302 Level: developer 4303 4304 Concepts: matrices^incomplete Cholesky factorization 4305 Concepts: Cholesky factorization 4306 4307 .seealso: MatIncompleteCholeskyFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 4308 @*/ 4309 int MatIncompleteCholeskyFactor(Mat mat,IS row,PetscReal fill,int level) 4310 { 4311 int ierr; 4312 4313 PetscFunctionBegin; 4314 PetscValidHeaderSpecific(mat,MAT_COOKIE); 4315 PetscValidType(mat); 4316 MatPreallocated(mat); 4317 if (mat->M != mat->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 4318 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4319 if (mat->factor) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4320 if (!mat->ops->incompletecholeskyfactor) SETERRQ(PETSC_ERR_SUP,""); 4321 4322 ierr = (*mat->ops->incompletecholeskyfactor)(mat,row,fill,level);CHKERRQ(ierr); 4323 PetscFunctionReturn(0); 4324 } 4325