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