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