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