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 PetscClassId PETSCMAT_DLLEXPORT MAT_CLASSID; 12 PetscClassId PETSCMAT_DLLEXPORT MAT_FDCOLORING_CLASSID; 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_CLASSID,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->factortype) 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_CLASSID,1); 132 PetscValidType(mat,1); 133 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 134 if (mat->factortype) 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_CLASSID,1); 166 PetscValidType(mat,1); 167 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 168 if (mat->factortype) 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_CLASSID,1); 200 PetscValidType(mat,1); 201 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 202 if (mat->factortype) 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_CLASSID,1); 234 PetscValidType(mat,1); 235 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 236 if (mat->factortype) 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_CLASSID,1); 312 PetscValidType(mat,1); 313 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 314 if (mat->factortype) 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_CLASSID,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_CLASSID,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_CLASSID,1); 424 PetscValidType(mat,1); 425 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 426 if (mat->factortype) 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_CLASSID,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_CLASSID,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_CLASSID,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_CLASSID,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_CLASSID,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_CLASSID,1); 682 PetscValidType(mat,1); 683 if (!viewer) { 684 ierr = PetscViewerASCIIGetStdout(((PetscObject)mat)->comm,&viewer);CHKERRQ(ierr); 685 } 686 PetscValidHeaderSpecific(viewer,PETSC_VIEWER_CLASSID,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->factortype) { 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_CLASSID,1); 767 PetscValidType(mat,1); 768 ierr = MatPreallocated(mat);CHKERRQ(ierr); 769 if (x) {PetscValidHeaderSpecific(x,VEC_CLASSID,3);PetscCheckSameComm(mat,1,x,3);} 770 if (b) {PetscValidHeaderSpecific(b,VEC_CLASSID,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_CLASSID,1); 809 PetscValidType(mat,1); 810 ierr = MatPreallocated(mat);CHKERRQ(ierr); 811 if (x) {PetscValidHeaderSpecific(x,VEC_CLASSID,3);PetscCheckSameComm(mat,1,x,3);} 812 if (b) {PetscValidHeaderSpecific(b,VEC_CLASSID,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_CLASSID,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_CLASSID,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)->classid != MAT_CLASSID) *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_CLASSID,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->factortype) 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_CLASSID,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_CLASSID,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->factortype) 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_CLASSID,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_CLASSID,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_CLASSID,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_CLASSID,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->factortype) 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_CLASSID,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->factortype) 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_CLASSID,1); 1571 PetscValidType(x,1); 1572 PetscValidHeaderSpecific(mapping,IS_LTOGM_CLASSID,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_CLASSID,1); 1615 PetscValidType(x,1); 1616 PetscValidHeaderSpecific(mapping,IS_LTOGM_CLASSID,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_CLASSID,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->factortype) 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_CLASSID,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->factortype) 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_CLASSID,1); 1835 PetscValidType(mat,1); 1836 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 1837 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 1838 1839 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1840 if (mat->factortype) 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_CLASSID,1); 1881 PetscValidType(mat,1); 1882 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 1883 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 1884 1885 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1886 if (mat->factortype) 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_CLASSID,1); 1941 PetscValidType(mat,1); 1942 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 1943 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 1944 1945 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1946 if (mat->factortype) 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_CLASSID,1); 1992 PetscValidType(mat,1); 1993 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 1994 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 1995 1996 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 1997 if (mat->factortype) 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_CLASSID,1); 2043 PetscValidType(mat,1); 2044 PetscValidHeaderSpecific(v1,VEC_CLASSID,2); 2045 PetscValidHeaderSpecific(v2,VEC_CLASSID,3); 2046 PetscValidHeaderSpecific(v3,VEC_CLASSID,4); 2047 2048 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2049 if (mat->factortype) 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_CLASSID,1); 2095 PetscValidType(mat,1); 2096 PetscValidHeaderSpecific(v1,VEC_CLASSID,2); 2097 PetscValidHeaderSpecific(v2,VEC_CLASSID,3); 2098 PetscValidHeaderSpecific(v3,VEC_CLASSID,4); 2099 2100 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2101 if (mat->factortype) 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_CLASSID,1); 2146 PetscValidType(mat,1); 2147 PetscValidHeaderSpecific(v1,VEC_CLASSID,2); 2148 PetscValidHeaderSpecific(v2,VEC_CLASSID,3); 2149 PetscValidHeaderSpecific(v3,VEC_CLASSID,4); 2150 2151 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2152 if (mat->factortype) 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_CLASSID,1); 2197 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 2198 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 2199 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2200 if (mat->factortype) 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_CLASSID,1); 2244 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 2245 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 2246 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 2247 if (mat->factortype) 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_CLASSID,1); 2282 PetscValidType(mat,1); 2283 *t = mat->factortype; 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_CLASSID,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_CLASSID,1); 2409 if (row) PetscValidHeaderSpecific(row,IS_CLASSID,2); 2410 if (col) PetscValidHeaderSpecific(col,IS_CLASSID,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->factortype) 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_CLASSID,1); 2466 if (row) PetscValidHeaderSpecific(row,IS_CLASSID,2); 2467 if (col) PetscValidHeaderSpecific(col,IS_CLASSID,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->factortype) 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_CLASSID,1); 2525 if (row) PetscValidHeaderSpecific(row,IS_CLASSID,2); 2526 if (col) PetscValidHeaderSpecific(col,IS_CLASSID,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->factortype) 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_CLASSID,1); 2579 PetscValidType(mat,1); 2580 PetscValidPointer(fact,2); 2581 PetscValidHeaderSpecific(fact,MAT_CLASSID,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_CLASSID,1); 2635 PetscValidType(mat,1); 2636 PetscValidHeaderSpecific(perm,IS_CLASSID,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->factortype) 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_CLASSID,1); 2693 PetscValidType(mat,1); 2694 if (perm) PetscValidHeaderSpecific(perm,IS_CLASSID,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->factortype) 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_CLASSID,1); 2747 PetscValidType(mat,1); 2748 PetscValidPointer(fact,2); 2749 PetscValidHeaderSpecific(fact,MAT_CLASSID,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_CLASSID,1); 2802 PetscValidType(mat,1); 2803 PetscValidHeaderSpecific(b,VEC_CLASSID,2); 2804 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 2888 PetscValidType(A,1); 2889 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 2890 PetscValidHeaderSpecific(X,MAT_CLASSID,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->factortype) 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_CLASSID,1); 2958 PetscValidType(mat,1); 2959 PetscValidHeaderSpecific(b,VEC_CLASSID,2); 2960 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 3021 PetscValidType(mat,1); 3022 PetscValidHeaderSpecific(b,VEC_CLASSID,2); 3023 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 3078 PetscValidType(mat,1); 3079 PetscValidHeaderSpecific(y,VEC_CLASSID,2); 3080 PetscValidHeaderSpecific(b,VEC_CLASSID,3); 3081 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 3150 PetscValidType(mat,1); 3151 PetscValidHeaderSpecific(b,VEC_CLASSID,2); 3152 PetscValidHeaderSpecific(x,VEC_CLASSID,3); 3153 PetscCheckSameComm(mat,1,b,2); 3154 PetscCheckSameComm(mat,1,x,3); 3155 if (!mat->factortype) 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_CLASSID,1); 3206 PetscValidType(mat,1); 3207 PetscValidHeaderSpecific(y,VEC_CLASSID,2); 3208 PetscValidHeaderSpecific(b,VEC_CLASSID,3); 3209 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 3308 PetscValidType(mat,1); 3309 PetscValidHeaderSpecific(b,VEC_CLASSID,2); 3310 PetscValidHeaderSpecific(x,VEC_CLASSID,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->factortype) 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_CLASSID,1); 3394 PetscValidHeaderSpecific(B,MAT_CLASSID,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->factortype) 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_CLASSID,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->factortype) 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_CLASSID,1); 3589 PetscValidType(mat,1); 3590 if (!mat->factortype) 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 ./configure 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_CLASSID,1); 3633 PetscValidType(mat,1); 3634 3635 if (mat->factortype) 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 ./configure 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 ./configure 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_CLASSID,1); 3688 PetscValidType(mat,1); 3689 3690 if (mat->factortype) 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_CLASSID,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->factortype) 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_CLASSID,1); 3797 PetscValidType(mat,1); 3798 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 3841 PetscValidType(mat,1); 3842 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 3884 PetscValidType(mat,1); 3885 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 3928 PetscValidType(mat,1); 3929 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 3971 PetscValidType(mat,1); 3972 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 4012 PetscValidType(mat,1); 4013 PetscValidHeaderSpecific(v,VEC_CLASSID,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_CLASSID,1); 4064 PetscValidType(mat,1); 4065 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4066 if (mat->factortype) 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_CLASSID,1); 4109 PetscValidHeaderSpecific(B,MAT_CLASSID,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_CLASSID,1); 4189 PetscValidHeaderSpecific(B,MAT_CLASSID,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_CLASSID,1); 4234 PetscValidType(mat,1); 4235 PetscValidHeaderSpecific(row,IS_CLASSID,2); 4236 PetscValidHeaderSpecific(col,IS_CLASSID,3); 4237 PetscValidPointer(B,4); 4238 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4239 if (mat->factortype) 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_CLASSID,1); 4294 PetscValidHeaderSpecific(rowp, IS_CLASSID,5); 4295 PetscValidHeaderSpecific(colp, IS_CLASSID,6); 4296 PetscValidPointer(B,7); 4297 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE, "Not for unassembled matrix"); 4298 if (A->factortype) 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_CLASSID,1); 4379 PetscValidHeaderSpecific(B,MAT_CLASSID,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 The L scales the rows of the matrix, the R scales the columns of the matrix. 4415 4416 Level: intermediate 4417 4418 Concepts: matrices^diagonal scaling 4419 Concepts: diagonal scaling of matrices 4420 4421 .seealso: MatScale() 4422 @*/ 4423 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScale(Mat mat,Vec l,Vec r) 4424 { 4425 PetscErrorCode ierr; 4426 4427 PetscFunctionBegin; 4428 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4429 PetscValidType(mat,1); 4430 if (!mat->ops->diagonalscale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 4431 if (l) {PetscValidHeaderSpecific(l,VEC_CLASSID,2);PetscCheckSameComm(mat,1,l,2);} 4432 if (r) {PetscValidHeaderSpecific(r,VEC_CLASSID,3);PetscCheckSameComm(mat,1,r,3);} 4433 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4434 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4435 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4436 4437 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 4438 ierr = (*mat->ops->diagonalscale)(mat,l,r);CHKERRQ(ierr); 4439 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 4440 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4441 PetscFunctionReturn(0); 4442 } 4443 4444 #undef __FUNCT__ 4445 #define __FUNCT__ "MatScale" 4446 /*@ 4447 MatScale - Scales all elements of a matrix by a given number. 4448 4449 Collective on Mat 4450 4451 Input Parameters: 4452 + mat - the matrix to be scaled 4453 - a - the scaling value 4454 4455 Output Parameter: 4456 . mat - the scaled matrix 4457 4458 Level: intermediate 4459 4460 Concepts: matrices^scaling all entries 4461 4462 .seealso: MatDiagonalScale() 4463 @*/ 4464 PetscErrorCode PETSCMAT_DLLEXPORT MatScale(Mat mat,PetscScalar a) 4465 { 4466 PetscErrorCode ierr; 4467 4468 PetscFunctionBegin; 4469 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4470 PetscValidType(mat,1); 4471 if (a != 1.0 && !mat->ops->scale) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 4472 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4473 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4474 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4475 4476 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 4477 if (a != 1.0) { 4478 ierr = (*mat->ops->scale)(mat,a);CHKERRQ(ierr); 4479 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4480 } 4481 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 4482 PetscFunctionReturn(0); 4483 } 4484 4485 #undef __FUNCT__ 4486 #define __FUNCT__ "MatNorm" 4487 /*@ 4488 MatNorm - Calculates various norms of a matrix. 4489 4490 Collective on Mat 4491 4492 Input Parameters: 4493 + mat - the matrix 4494 - type - the type of norm, NORM_1, NORM_FROBENIUS, NORM_INFINITY 4495 4496 Output Parameters: 4497 . nrm - the resulting norm 4498 4499 Level: intermediate 4500 4501 Concepts: matrices^norm 4502 Concepts: norm^of matrix 4503 @*/ 4504 PetscErrorCode PETSCMAT_DLLEXPORT MatNorm(Mat mat,NormType type,PetscReal *nrm) 4505 { 4506 PetscErrorCode ierr; 4507 4508 PetscFunctionBegin; 4509 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4510 PetscValidType(mat,1); 4511 PetscValidScalarPointer(nrm,3); 4512 4513 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 4514 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4515 if (!mat->ops->norm) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 4516 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4517 4518 ierr = (*mat->ops->norm)(mat,type,nrm);CHKERRQ(ierr); 4519 PetscFunctionReturn(0); 4520 } 4521 4522 /* 4523 This variable is used to prevent counting of MatAssemblyBegin() that 4524 are called from within a MatAssemblyEnd(). 4525 */ 4526 static PetscInt MatAssemblyEnd_InUse = 0; 4527 #undef __FUNCT__ 4528 #define __FUNCT__ "MatAssemblyBegin" 4529 /*@ 4530 MatAssemblyBegin - Begins assembling the matrix. This routine should 4531 be called after completing all calls to MatSetValues(). 4532 4533 Collective on Mat 4534 4535 Input Parameters: 4536 + mat - the matrix 4537 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 4538 4539 Notes: 4540 MatSetValues() generally caches the values. The matrix is ready to 4541 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 4542 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 4543 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 4544 using the matrix. 4545 4546 Level: beginner 4547 4548 Concepts: matrices^assembling 4549 4550 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssembled() 4551 @*/ 4552 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyBegin(Mat mat,MatAssemblyType type) 4553 { 4554 PetscErrorCode ierr; 4555 4556 PetscFunctionBegin; 4557 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4558 PetscValidType(mat,1); 4559 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4560 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix.\nDid you forget to call MatSetUnfactored()?"); 4561 if (mat->assembled) { 4562 mat->was_assembled = PETSC_TRUE; 4563 mat->assembled = PETSC_FALSE; 4564 } 4565 if (!MatAssemblyEnd_InUse) { 4566 ierr = PetscLogEventBegin(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 4567 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 4568 ierr = PetscLogEventEnd(MAT_AssemblyBegin,mat,0,0,0);CHKERRQ(ierr); 4569 } else { 4570 if (mat->ops->assemblybegin){ierr = (*mat->ops->assemblybegin)(mat,type);CHKERRQ(ierr);} 4571 } 4572 PetscFunctionReturn(0); 4573 } 4574 4575 #undef __FUNCT__ 4576 #define __FUNCT__ "MatAssembled" 4577 /*@ 4578 MatAssembled - Indicates if a matrix has been assembled and is ready for 4579 use; for example, in matrix-vector product. 4580 4581 Collective on Mat 4582 4583 Input Parameter: 4584 . mat - the matrix 4585 4586 Output Parameter: 4587 . assembled - PETSC_TRUE or PETSC_FALSE 4588 4589 Level: advanced 4590 4591 Concepts: matrices^assembled? 4592 4593 .seealso: MatAssemblyEnd(), MatSetValues(), MatAssemblyBegin() 4594 @*/ 4595 PetscErrorCode PETSCMAT_DLLEXPORT MatAssembled(Mat mat,PetscTruth *assembled) 4596 { 4597 PetscFunctionBegin; 4598 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4599 PetscValidType(mat,1); 4600 PetscValidPointer(assembled,2); 4601 *assembled = mat->assembled; 4602 PetscFunctionReturn(0); 4603 } 4604 4605 #undef __FUNCT__ 4606 #define __FUNCT__ "MatView_Private" 4607 /* 4608 Processes command line options to determine if/how a matrix 4609 is to be viewed. Called by MatAssemblyEnd() and MatLoad(). 4610 */ 4611 PetscErrorCode MatView_Private(Mat mat) 4612 { 4613 PetscErrorCode ierr; 4614 PetscTruth flg1 = PETSC_FALSE,flg2 = PETSC_FALSE,flg3 = PETSC_FALSE,flg4 = PETSC_FALSE,flg6 = PETSC_FALSE,flg7 = PETSC_FALSE,flg8 = PETSC_FALSE; 4615 static PetscTruth incall = PETSC_FALSE; 4616 #if defined(PETSC_USE_SOCKET_VIEWER) 4617 PetscTruth flg5 = PETSC_FALSE; 4618 #endif 4619 4620 PetscFunctionBegin; 4621 if (incall) PetscFunctionReturn(0); 4622 incall = PETSC_TRUE; 4623 ierr = PetscOptionsBegin(((PetscObject)mat)->comm,((PetscObject)mat)->prefix,"Matrix Options","Mat");CHKERRQ(ierr); 4624 ierr = PetscOptionsTruth("-mat_view_info","Information on matrix size","MatView",flg1,&flg1,PETSC_NULL);CHKERRQ(ierr); 4625 ierr = PetscOptionsTruth("-mat_view_info_detailed","Nonzeros in the matrix","MatView",flg2,&flg2,PETSC_NULL);CHKERRQ(ierr); 4626 ierr = PetscOptionsTruth("-mat_view","Print matrix to stdout","MatView",flg3,&flg3,PETSC_NULL);CHKERRQ(ierr); 4627 ierr = PetscOptionsTruth("-mat_view_matlab","Print matrix to stdout in a format Matlab can read","MatView",flg4,&flg4,PETSC_NULL);CHKERRQ(ierr); 4628 #if defined(PETSC_USE_SOCKET_VIEWER) 4629 ierr = PetscOptionsTruth("-mat_view_socket","Send matrix to socket (can be read from matlab)","MatView",flg5,&flg5,PETSC_NULL);CHKERRQ(ierr); 4630 #endif 4631 ierr = PetscOptionsTruth("-mat_view_binary","Save matrix to file in binary format","MatView",flg6,&flg6,PETSC_NULL);CHKERRQ(ierr); 4632 ierr = PetscOptionsTruth("-mat_view_draw","Draw the matrix nonzero structure","MatView",flg7,&flg7,PETSC_NULL);CHKERRQ(ierr); 4633 ierr = PetscOptionsEnd();CHKERRQ(ierr); 4634 4635 if (flg1) { 4636 PetscViewer viewer; 4637 4638 ierr = PetscViewerASCIIGetStdout(((PetscObject)mat)->comm,&viewer);CHKERRQ(ierr); 4639 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);CHKERRQ(ierr); 4640 ierr = MatView(mat,viewer);CHKERRQ(ierr); 4641 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 4642 } 4643 if (flg2) { 4644 PetscViewer viewer; 4645 4646 ierr = PetscViewerASCIIGetStdout(((PetscObject)mat)->comm,&viewer);CHKERRQ(ierr); 4647 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO_DETAIL);CHKERRQ(ierr); 4648 ierr = MatView(mat,viewer);CHKERRQ(ierr); 4649 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 4650 } 4651 if (flg3) { 4652 PetscViewer viewer; 4653 4654 ierr = PetscViewerASCIIGetStdout(((PetscObject)mat)->comm,&viewer);CHKERRQ(ierr); 4655 ierr = MatView(mat,viewer);CHKERRQ(ierr); 4656 } 4657 if (flg4) { 4658 PetscViewer viewer; 4659 4660 ierr = PetscViewerASCIIGetStdout(((PetscObject)mat)->comm,&viewer);CHKERRQ(ierr); 4661 ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);CHKERRQ(ierr); 4662 ierr = MatView(mat,viewer);CHKERRQ(ierr); 4663 ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr); 4664 } 4665 #if defined(PETSC_USE_SOCKET_VIEWER) 4666 if (flg5) { 4667 ierr = MatView(mat,PETSC_VIEWER_SOCKET_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4668 ierr = PetscViewerFlush(PETSC_VIEWER_SOCKET_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4669 } 4670 #endif 4671 if (flg6) { 4672 ierr = MatView(mat,PETSC_VIEWER_BINARY_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4673 ierr = PetscViewerFlush(PETSC_VIEWER_BINARY_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4674 } 4675 if (flg7) { 4676 ierr = PetscOptionsGetTruth(((PetscObject)mat)->prefix,"-mat_view_contour",&flg8,PETSC_NULL);CHKERRQ(ierr); 4677 if (flg8) { 4678 PetscViewerPushFormat(PETSC_VIEWER_DRAW_(((PetscObject)mat)->comm),PETSC_VIEWER_DRAW_CONTOUR);CHKERRQ(ierr); 4679 } 4680 ierr = MatView(mat,PETSC_VIEWER_DRAW_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4681 ierr = PetscViewerFlush(PETSC_VIEWER_DRAW_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4682 if (flg8) { 4683 PetscViewerPopFormat(PETSC_VIEWER_DRAW_(((PetscObject)mat)->comm));CHKERRQ(ierr); 4684 } 4685 } 4686 incall = PETSC_FALSE; 4687 PetscFunctionReturn(0); 4688 } 4689 4690 #undef __FUNCT__ 4691 #define __FUNCT__ "MatAssemblyEnd" 4692 /*@ 4693 MatAssemblyEnd - Completes assembling the matrix. This routine should 4694 be called after MatAssemblyBegin(). 4695 4696 Collective on Mat 4697 4698 Input Parameters: 4699 + mat - the matrix 4700 - type - type of assembly, either MAT_FLUSH_ASSEMBLY or MAT_FINAL_ASSEMBLY 4701 4702 Options Database Keys: 4703 + -mat_view_info - Prints info on matrix at conclusion of MatEndAssembly() 4704 . -mat_view_info_detailed - Prints more detailed info 4705 . -mat_view - Prints matrix in ASCII format 4706 . -mat_view_matlab - Prints matrix in Matlab format 4707 . -mat_view_draw - PetscDraws nonzero structure of matrix, using MatView() and PetscDrawOpenX(). 4708 . -display <name> - Sets display name (default is host) 4709 . -draw_pause <sec> - Sets number of seconds to pause after display 4710 . -mat_view_socket - Sends matrix to socket, can be accessed from Matlab (see users manual) 4711 . -viewer_socket_machine <machine> 4712 . -viewer_socket_port <port> 4713 . -mat_view_binary - save matrix to file in binary format 4714 - -viewer_binary_filename <name> 4715 4716 Notes: 4717 MatSetValues() generally caches the values. The matrix is ready to 4718 use only after MatAssemblyBegin() and MatAssemblyEnd() have been called. 4719 Use MAT_FLUSH_ASSEMBLY when switching between ADD_VALUES and INSERT_VALUES 4720 in MatSetValues(); use MAT_FINAL_ASSEMBLY for the final assembly before 4721 using the matrix. 4722 4723 Level: beginner 4724 4725 .seealso: MatAssemblyBegin(), MatSetValues(), PetscDrawOpenX(), MatView(), MatAssembled(), PetscViewerSocketOpen() 4726 @*/ 4727 PetscErrorCode PETSCMAT_DLLEXPORT MatAssemblyEnd(Mat mat,MatAssemblyType type) 4728 { 4729 PetscErrorCode ierr; 4730 static PetscInt inassm = 0; 4731 PetscTruth flg = PETSC_FALSE; 4732 4733 PetscFunctionBegin; 4734 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4735 PetscValidType(mat,1); 4736 4737 inassm++; 4738 MatAssemblyEnd_InUse++; 4739 if (MatAssemblyEnd_InUse == 1) { /* Do the logging only the first time through */ 4740 ierr = PetscLogEventBegin(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 4741 if (mat->ops->assemblyend) { 4742 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 4743 } 4744 ierr = PetscLogEventEnd(MAT_AssemblyEnd,mat,0,0,0);CHKERRQ(ierr); 4745 } else { 4746 if (mat->ops->assemblyend) { 4747 ierr = (*mat->ops->assemblyend)(mat,type);CHKERRQ(ierr); 4748 } 4749 } 4750 4751 /* Flush assembly is not a true assembly */ 4752 if (type != MAT_FLUSH_ASSEMBLY) { 4753 mat->assembled = PETSC_TRUE; mat->num_ass++; 4754 } 4755 mat->insertmode = NOT_SET_VALUES; 4756 MatAssemblyEnd_InUse--; 4757 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4758 if (!mat->symmetric_eternal) { 4759 mat->symmetric_set = PETSC_FALSE; 4760 mat->hermitian_set = PETSC_FALSE; 4761 mat->structurally_symmetric_set = PETSC_FALSE; 4762 } 4763 if (inassm == 1 && type != MAT_FLUSH_ASSEMBLY) { 4764 ierr = MatView_Private(mat);CHKERRQ(ierr); 4765 ierr = PetscOptionsGetTruth(((PetscObject)mat)->prefix,"-mat_is_symmetric",&flg,PETSC_NULL);CHKERRQ(ierr); 4766 if (flg) { 4767 PetscReal tol = 0.0; 4768 ierr = PetscOptionsGetReal(((PetscObject)mat)->prefix,"-mat_is_symmetric",&tol,PETSC_NULL);CHKERRQ(ierr); 4769 ierr = MatIsSymmetric(mat,tol,&flg);CHKERRQ(ierr); 4770 if (flg) { 4771 ierr = PetscPrintf(((PetscObject)mat)->comm,"Matrix is symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 4772 } else { 4773 ierr = PetscPrintf(((PetscObject)mat)->comm,"Matrix is not symmetric (tolerance %G)\n",tol);CHKERRQ(ierr); 4774 } 4775 } 4776 } 4777 inassm--; 4778 PetscFunctionReturn(0); 4779 } 4780 4781 #undef __FUNCT__ 4782 #define __FUNCT__ "MatSetOption" 4783 /*@ 4784 MatSetOption - Sets a parameter option for a matrix. Some options 4785 may be specific to certain storage formats. Some options 4786 determine how values will be inserted (or added). Sorted, 4787 row-oriented input will generally assemble the fastest. The default 4788 is row-oriented, nonsorted input. 4789 4790 Collective on Mat 4791 4792 Input Parameters: 4793 + mat - the matrix 4794 . option - the option, one of those listed below (and possibly others), 4795 - flg - turn the option on (PETSC_TRUE) or off (PETSC_FALSE) 4796 4797 Options Describing Matrix Structure: 4798 + MAT_SYMMETRIC - symmetric in terms of both structure and value 4799 . MAT_HERMITIAN - transpose is the complex conjugation 4800 . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 4801 - MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag 4802 you set to be kept with all future use of the matrix 4803 including after MatAssemblyBegin/End() which could 4804 potentially change the symmetry structure, i.e. you 4805 KNOW the matrix will ALWAYS have the property you set. 4806 4807 4808 Options For Use with MatSetValues(): 4809 Insert a logically dense subblock, which can be 4810 . MAT_ROW_ORIENTED - row-oriented (default) 4811 4812 Note these options reflect the data you pass in with MatSetValues(); it has 4813 nothing to do with how the data is stored internally in the matrix 4814 data structure. 4815 4816 When (re)assembling a matrix, we can restrict the input for 4817 efficiency/debugging purposes. These options include 4818 + MAT_NEW_NONZERO_LOCATIONS - additional insertions will be 4819 allowed if they generate a new nonzero 4820 . MAT_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 4821 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 4822 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 4823 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 4824 4825 Notes: 4826 Some options are relevant only for particular matrix types and 4827 are thus ignored by others. Other options are not supported by 4828 certain matrix types and will generate an error message if set. 4829 4830 If using a Fortran 77 module to compute a matrix, one may need to 4831 use the column-oriented option (or convert to the row-oriented 4832 format). 4833 4834 MAT_NEW_NONZERO_LOCATIONS set to PETSC_FALSE indicates that any add or insertion 4835 that would generate a new entry in the nonzero structure is instead 4836 ignored. Thus, if memory has not alredy been allocated for this particular 4837 data, then the insertion is ignored. For dense matrices, in which 4838 the entire array is allocated, no entries are ever ignored. 4839 Set after the first MatAssemblyEnd() 4840 4841 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 4842 that would generate a new entry in the nonzero structure instead produces 4843 an error. (Currently supported for AIJ and BAIJ formats only.) 4844 This is a useful flag when using SAME_NONZERO_PATTERN in calling 4845 KSPSetOperators() to ensure that the nonzero pattern truely does 4846 remain unchanged. Set after the first MatAssemblyEnd() 4847 4848 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 4849 that would generate a new entry that has not been preallocated will 4850 instead produce an error. (Currently supported for AIJ and BAIJ formats 4851 only.) This is a useful flag when debugging matrix memory preallocation. 4852 4853 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 4854 other processors should be dropped, rather than stashed. 4855 This is useful if you know that the "owning" processor is also 4856 always generating the correct matrix entries, so that PETSc need 4857 not transfer duplicate entries generated on another processor. 4858 4859 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 4860 searches during matrix assembly. When this flag is set, the hash table 4861 is created during the first Matrix Assembly. This hash table is 4862 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 4863 to improve the searching of indices. MAT_NEW_NONZERO_LOCATIONS flag 4864 should be used with MAT_USE_HASH_TABLE flag. This option is currently 4865 supported by MATMPIBAIJ format only. 4866 4867 MAT_KEEP_NONZERO_PATTERN indicates when MatZeroRows() is called the zeroed entries 4868 are kept in the nonzero structure 4869 4870 MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating 4871 a zero location in the matrix 4872 4873 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 4874 ROWBS matrix types 4875 4876 Level: intermediate 4877 4878 Concepts: matrices^setting options 4879 4880 @*/ 4881 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op,PetscTruth flg) 4882 { 4883 PetscErrorCode ierr; 4884 4885 PetscFunctionBegin; 4886 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4887 PetscValidType(mat,1); 4888 if (((int) op) < 0 || ((int) op) >= NUM_MAT_OPTIONS) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Options %d is out of range",(int)op); 4889 if (!((PetscObject)mat)->type_name) SETERRQ(PETSC_ERR_ARG_TYPENOTSET,"Cannot set options until type and size have been set, see MatSetType() and MatSetSizes()"); 4890 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4891 switch (op) { 4892 case MAT_SYMMETRIC: 4893 mat->symmetric = flg; 4894 if (flg) mat->structurally_symmetric = PETSC_TRUE; 4895 mat->symmetric_set = PETSC_TRUE; 4896 mat->structurally_symmetric_set = flg; 4897 break; 4898 case MAT_HERMITIAN: 4899 mat->hermitian = flg; 4900 if (flg) mat->structurally_symmetric = PETSC_TRUE; 4901 mat->hermitian_set = PETSC_TRUE; 4902 mat->structurally_symmetric_set = flg; 4903 break; 4904 case MAT_STRUCTURALLY_SYMMETRIC: 4905 mat->structurally_symmetric = flg; 4906 mat->structurally_symmetric_set = PETSC_TRUE; 4907 break; 4908 case MAT_SYMMETRY_ETERNAL: 4909 mat->symmetric_eternal = flg; 4910 break; 4911 default: 4912 break; 4913 } 4914 if (mat->ops->setoption) { 4915 ierr = (*mat->ops->setoption)(mat,op,flg);CHKERRQ(ierr); 4916 } 4917 PetscFunctionReturn(0); 4918 } 4919 4920 #undef __FUNCT__ 4921 #define __FUNCT__ "MatZeroEntries" 4922 /*@ 4923 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 4924 this routine retains the old nonzero structure. 4925 4926 Collective on Mat 4927 4928 Input Parameters: 4929 . mat - the matrix 4930 4931 Level: intermediate 4932 4933 Concepts: matrices^zeroing 4934 4935 .seealso: MatZeroRows() 4936 @*/ 4937 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat) 4938 { 4939 PetscErrorCode ierr; 4940 4941 PetscFunctionBegin; 4942 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 4943 PetscValidType(mat,1); 4944 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 4945 if (mat->insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for matrices where you have set values but not yet assembled"); 4946 if (!mat->ops->zeroentries) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 4947 ierr = MatPreallocated(mat);CHKERRQ(ierr); 4948 4949 ierr = PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4950 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 4951 ierr = PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 4952 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 4953 PetscFunctionReturn(0); 4954 } 4955 4956 #undef __FUNCT__ 4957 #define __FUNCT__ "MatZeroRows" 4958 /*@C 4959 MatZeroRows - Zeros all entries (except possibly the main diagonal) 4960 of a set of rows of a matrix. 4961 4962 Collective on Mat 4963 4964 Input Parameters: 4965 + mat - the matrix 4966 . numRows - the number of rows to remove 4967 . rows - the global row indices 4968 - diag - value put in all diagonals of eliminated rows (0.0 will even eliminate diagonal entry) 4969 4970 Notes: 4971 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 4972 but does not release memory. For the dense and block diagonal 4973 formats this does not alter the nonzero structure. 4974 4975 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 4976 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 4977 merely zeroed. 4978 4979 The user can set a value in the diagonal entry (or for the AIJ and 4980 row formats can optionally remove the main diagonal entry from the 4981 nonzero structure as well, by passing 0.0 as the final argument). 4982 4983 For the parallel case, all processes that share the matrix (i.e., 4984 those in the communicator used for matrix creation) MUST call this 4985 routine, regardless of whether any rows being zeroed are owned by 4986 them. 4987 4988 Each processor can indicate any rows in the entire matrix to be zeroed (i.e. each process does NOT have to 4989 list only rows local to itself). 4990 4991 Level: intermediate 4992 4993 Concepts: matrices^zeroing rows 4994 4995 .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 4996 @*/ 4997 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 4998 { 4999 PetscErrorCode ierr; 5000 5001 PetscFunctionBegin; 5002 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5003 PetscValidType(mat,1); 5004 if (numRows) PetscValidIntPointer(rows,3); 5005 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5006 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5007 if (!mat->ops->zerorows) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5008 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5009 5010 ierr = (*mat->ops->zerorows)(mat,numRows,rows,diag);CHKERRQ(ierr); 5011 ierr = MatView_Private(mat);CHKERRQ(ierr); 5012 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5013 PetscFunctionReturn(0); 5014 } 5015 5016 #undef __FUNCT__ 5017 #define __FUNCT__ "MatZeroRowsIS" 5018 /*@C 5019 MatZeroRowsIS - Zeros all entries (except possibly the main diagonal) 5020 of a set of rows of a matrix. 5021 5022 Collective on Mat 5023 5024 Input Parameters: 5025 + mat - the matrix 5026 . is - index set of rows to remove 5027 - diag - value put in all diagonals of eliminated rows 5028 5029 Notes: 5030 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 5031 but does not release memory. For the dense and block diagonal 5032 formats this does not alter the nonzero structure. 5033 5034 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5035 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5036 merely zeroed. 5037 5038 The user can set a value in the diagonal entry (or for the AIJ and 5039 row formats can optionally remove the main diagonal entry from the 5040 nonzero structure as well, by passing 0.0 as the final argument). 5041 5042 For the parallel case, all processes that share the matrix (i.e., 5043 those in the communicator used for matrix creation) MUST call this 5044 routine, regardless of whether any rows being zeroed are owned by 5045 them. 5046 5047 Each processor should list the rows that IT wants zeroed 5048 5049 Level: intermediate 5050 5051 Concepts: matrices^zeroing rows 5052 5053 .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 5054 @*/ 5055 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag) 5056 { 5057 PetscInt numRows; 5058 const PetscInt *rows; 5059 PetscErrorCode ierr; 5060 5061 PetscFunctionBegin; 5062 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5063 PetscValidType(mat,1); 5064 PetscValidHeaderSpecific(is,IS_CLASSID,2); 5065 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 5066 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 5067 ierr = MatZeroRows(mat,numRows,rows,diag);CHKERRQ(ierr); 5068 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 5069 PetscFunctionReturn(0); 5070 } 5071 5072 #undef __FUNCT__ 5073 #define __FUNCT__ "MatZeroRowsLocal" 5074 /*@C 5075 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 5076 of a set of rows of a matrix; using local numbering of rows. 5077 5078 Collective on Mat 5079 5080 Input Parameters: 5081 + mat - the matrix 5082 . numRows - the number of rows to remove 5083 . rows - the global row indices 5084 - diag - value put in all diagonals of eliminated rows 5085 5086 Notes: 5087 Before calling MatZeroRowsLocal(), the user must first set the 5088 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 5089 5090 For the AIJ matrix formats this removes the old nonzero structure, 5091 but does not release memory. For the dense and block diagonal 5092 formats this does not alter the nonzero structure. 5093 5094 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5095 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5096 merely zeroed. 5097 5098 The user can set a value in the diagonal entry (or for the AIJ and 5099 row formats can optionally remove the main diagonal entry from the 5100 nonzero structure as well, by passing 0.0 as the final argument). 5101 5102 Level: intermediate 5103 5104 Concepts: matrices^zeroing 5105 5106 .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 5107 @*/ 5108 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 5109 { 5110 PetscErrorCode ierr; 5111 5112 PetscFunctionBegin; 5113 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5114 PetscValidType(mat,1); 5115 if (numRows) PetscValidIntPointer(rows,3); 5116 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5117 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5118 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5119 5120 if (mat->ops->zerorowslocal) { 5121 ierr = (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);CHKERRQ(ierr); 5122 } else { 5123 IS is, newis; 5124 const PetscInt *newRows; 5125 5126 if (!mat->mapping) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 5127 ierr = ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);CHKERRQ(ierr); 5128 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 5129 ierr = ISGetIndices(newis,&newRows);CHKERRQ(ierr); 5130 ierr = (*mat->ops->zerorows)(mat,numRows,newRows,diag);CHKERRQ(ierr); 5131 ierr = ISRestoreIndices(newis,&newRows);CHKERRQ(ierr); 5132 ierr = ISDestroy(newis);CHKERRQ(ierr); 5133 ierr = ISDestroy(is);CHKERRQ(ierr); 5134 } 5135 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5136 PetscFunctionReturn(0); 5137 } 5138 5139 #undef __FUNCT__ 5140 #define __FUNCT__ "MatZeroRowsLocalIS" 5141 /*@C 5142 MatZeroRowsLocalIS - Zeros all entries (except possibly the main diagonal) 5143 of a set of rows of a matrix; using local numbering of rows. 5144 5145 Collective on Mat 5146 5147 Input Parameters: 5148 + mat - the matrix 5149 . is - index set of rows to remove 5150 - diag - value put in all diagonals of eliminated rows 5151 5152 Notes: 5153 Before calling MatZeroRowsLocalIS(), the user must first set the 5154 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 5155 5156 For the AIJ matrix formats this removes the old nonzero structure, 5157 but does not release memory. For the dense and block diagonal 5158 formats this does not alter the nonzero structure. 5159 5160 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5161 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5162 merely zeroed. 5163 5164 The user can set a value in the diagonal entry (or for the AIJ and 5165 row formats can optionally remove the main diagonal entry from the 5166 nonzero structure as well, by passing 0.0 as the final argument). 5167 5168 Level: intermediate 5169 5170 Concepts: matrices^zeroing 5171 5172 .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 5173 @*/ 5174 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag) 5175 { 5176 PetscErrorCode ierr; 5177 PetscInt numRows; 5178 const PetscInt *rows; 5179 5180 PetscFunctionBegin; 5181 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5182 PetscValidType(mat,1); 5183 PetscValidHeaderSpecific(is,IS_CLASSID,2); 5184 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5185 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5186 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5187 5188 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 5189 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 5190 ierr = MatZeroRowsLocal(mat,numRows,rows,diag);CHKERRQ(ierr); 5191 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 5192 PetscFunctionReturn(0); 5193 } 5194 5195 #undef __FUNCT__ 5196 #define __FUNCT__ "MatGetSize" 5197 /*@ 5198 MatGetSize - Returns the numbers of rows and columns in a matrix. 5199 5200 Not Collective 5201 5202 Input Parameter: 5203 . mat - the matrix 5204 5205 Output Parameters: 5206 + m - the number of global rows 5207 - n - the number of global columns 5208 5209 Note: both output parameters can be PETSC_NULL on input. 5210 5211 Level: beginner 5212 5213 Concepts: matrices^size 5214 5215 .seealso: MatGetLocalSize() 5216 @*/ 5217 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n) 5218 { 5219 PetscFunctionBegin; 5220 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5221 if (m) *m = mat->rmap->N; 5222 if (n) *n = mat->cmap->N; 5223 PetscFunctionReturn(0); 5224 } 5225 5226 #undef __FUNCT__ 5227 #define __FUNCT__ "MatGetLocalSize" 5228 /*@ 5229 MatGetLocalSize - Returns the number of rows and columns in a matrix 5230 stored locally. This information may be implementation dependent, so 5231 use with care. 5232 5233 Not Collective 5234 5235 Input Parameters: 5236 . mat - the matrix 5237 5238 Output Parameters: 5239 + m - the number of local rows 5240 - n - the number of local columns 5241 5242 Note: both output parameters can be PETSC_NULL on input. 5243 5244 Level: beginner 5245 5246 Concepts: matrices^local size 5247 5248 .seealso: MatGetSize() 5249 @*/ 5250 PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n) 5251 { 5252 PetscFunctionBegin; 5253 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5254 if (m) PetscValidIntPointer(m,2); 5255 if (n) PetscValidIntPointer(n,3); 5256 if (m) *m = mat->rmap->n; 5257 if (n) *n = mat->cmap->n; 5258 PetscFunctionReturn(0); 5259 } 5260 5261 #undef __FUNCT__ 5262 #define __FUNCT__ "MatGetOwnershipRangeColumn" 5263 /*@ 5264 MatGetOwnershipRangeColumn - Returns the range of matrix columns owned by 5265 this processor. 5266 5267 Not Collective, unless matrix has not been allocated, then collective on Mat 5268 5269 Input Parameters: 5270 . mat - the matrix 5271 5272 Output Parameters: 5273 + m - the global index of the first local column 5274 - n - one more than the global index of the last local column 5275 5276 Notes: both output parameters can be PETSC_NULL on input. 5277 5278 Level: developer 5279 5280 Concepts: matrices^column ownership 5281 5282 .seealso: MatGetOwnershipRange(), MatGetOwnershipRanges(), MatGetOwnershipRangesColumn() 5283 5284 @*/ 5285 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRangeColumn(Mat mat,PetscInt *m,PetscInt* n) 5286 { 5287 PetscErrorCode ierr; 5288 5289 PetscFunctionBegin; 5290 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5291 PetscValidType(mat,1); 5292 if (m) PetscValidIntPointer(m,2); 5293 if (n) PetscValidIntPointer(n,3); 5294 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5295 if (m) *m = mat->cmap->rstart; 5296 if (n) *n = mat->cmap->rend; 5297 PetscFunctionReturn(0); 5298 } 5299 5300 #undef __FUNCT__ 5301 #define __FUNCT__ "MatGetOwnershipRange" 5302 /*@ 5303 MatGetOwnershipRange - Returns the range of matrix rows owned by 5304 this processor, assuming that the matrix is laid out with the first 5305 n1 rows on the first processor, the next n2 rows on the second, etc. 5306 For certain parallel layouts this range may not be well defined. 5307 5308 Not Collective, unless matrix has not been allocated, then collective on Mat 5309 5310 Input Parameters: 5311 . mat - the matrix 5312 5313 Output Parameters: 5314 + m - the global index of the first local row 5315 - n - one more than the global index of the last local row 5316 5317 Note: both output parameters can be PETSC_NULL on input. 5318 5319 Level: beginner 5320 5321 Concepts: matrices^row ownership 5322 5323 .seealso: MatGetOwnershipRanges(), MatGetOwnershipRangeColumn(), MatGetOwnershipRangesColumn() 5324 5325 @*/ 5326 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n) 5327 { 5328 PetscErrorCode ierr; 5329 5330 PetscFunctionBegin; 5331 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5332 PetscValidType(mat,1); 5333 if (m) PetscValidIntPointer(m,2); 5334 if (n) PetscValidIntPointer(n,3); 5335 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5336 if (m) *m = mat->rmap->rstart; 5337 if (n) *n = mat->rmap->rend; 5338 PetscFunctionReturn(0); 5339 } 5340 5341 #undef __FUNCT__ 5342 #define __FUNCT__ "MatGetOwnershipRanges" 5343 /*@C 5344 MatGetOwnershipRanges - Returns the range of matrix rows owned by 5345 each process 5346 5347 Not Collective, unless matrix has not been allocated, then collective on Mat 5348 5349 Input Parameters: 5350 . mat - the matrix 5351 5352 Output Parameters: 5353 . ranges - start of each processors portion plus one more then the total length at the end 5354 5355 Level: beginner 5356 5357 Concepts: matrices^row ownership 5358 5359 .seealso: MatGetOwnershipRange(), MatGetOwnershipRangeColumn(), MatGetOwnershipRangesColumn() 5360 5361 @*/ 5362 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRanges(Mat mat,const PetscInt **ranges) 5363 { 5364 PetscErrorCode ierr; 5365 5366 PetscFunctionBegin; 5367 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5368 PetscValidType(mat,1); 5369 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5370 ierr = PetscLayoutGetRanges(mat->rmap,ranges);CHKERRQ(ierr); 5371 PetscFunctionReturn(0); 5372 } 5373 5374 #undef __FUNCT__ 5375 #define __FUNCT__ "MatGetOwnershipRangesColumn" 5376 /*@C 5377 MatGetOwnershipRangesColumn - Returns the range of local columns for each process 5378 5379 Not Collective, unless matrix has not been allocated, then collective on Mat 5380 5381 Input Parameters: 5382 . mat - the matrix 5383 5384 Output Parameters: 5385 . ranges - start of each processors portion plus one more then the total length at the end 5386 5387 Level: beginner 5388 5389 Concepts: matrices^column ownership 5390 5391 .seealso: MatGetOwnershipRange(), MatGetOwnershipRangeColumn(), MatGetOwnershipRanges() 5392 5393 @*/ 5394 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRangesColumn(Mat mat,const PetscInt **ranges) 5395 { 5396 PetscErrorCode ierr; 5397 5398 PetscFunctionBegin; 5399 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5400 PetscValidType(mat,1); 5401 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5402 ierr = PetscLayoutGetRanges(mat->cmap,ranges);CHKERRQ(ierr); 5403 PetscFunctionReturn(0); 5404 } 5405 5406 #undef __FUNCT__ 5407 #define __FUNCT__ "MatILUFactorSymbolic" 5408 /*@C 5409 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 5410 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 5411 to complete the factorization. 5412 5413 Collective on Mat 5414 5415 Input Parameters: 5416 + mat - the matrix 5417 . row - row permutation 5418 . column - column permutation 5419 - info - structure containing 5420 $ levels - number of levels of fill. 5421 $ expected fill - as ratio of original fill. 5422 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 5423 missing diagonal entries) 5424 5425 Output Parameters: 5426 . fact - new matrix that has been symbolically factored 5427 5428 Notes: 5429 See the users manual for additional information about 5430 choosing the fill factor for better efficiency. 5431 5432 Most users should employ the simplified KSP interface for linear solvers 5433 instead of working directly with matrix algebra routines such as this. 5434 See, e.g., KSPCreate(). 5435 5436 Level: developer 5437 5438 Concepts: matrices^symbolic LU factorization 5439 Concepts: matrices^factorization 5440 Concepts: LU^symbolic factorization 5441 5442 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 5443 MatGetOrdering(), MatFactorInfo 5444 5445 Developer Note: fortran interface is not autogenerated as the f90 5446 interface defintion cannot be generated correctly [due to MatFactorInfo] 5447 5448 @*/ 5449 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat fact,Mat mat,IS row,IS col,const MatFactorInfo *info) 5450 { 5451 PetscErrorCode ierr; 5452 5453 PetscFunctionBegin; 5454 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5455 PetscValidType(mat,1); 5456 PetscValidHeaderSpecific(row,IS_CLASSID,2); 5457 PetscValidHeaderSpecific(col,IS_CLASSID,3); 5458 PetscValidPointer(info,4); 5459 PetscValidPointer(fact,5); 5460 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels); 5461 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 5462 if (!(fact)->ops->ilufactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ILU",((PetscObject)mat)->type_name); 5463 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5464 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5465 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5466 5467 ierr = PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 5468 ierr = (fact->ops->ilufactorsymbolic)(fact,mat,row,col,info);CHKERRQ(ierr); 5469 ierr = PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 5470 PetscFunctionReturn(0); 5471 } 5472 5473 #undef __FUNCT__ 5474 #define __FUNCT__ "MatICCFactorSymbolic" 5475 /*@C 5476 MatICCFactorSymbolic - Performs symbolic incomplete 5477 Cholesky factorization for a symmetric matrix. Use 5478 MatCholeskyFactorNumeric() to complete the factorization. 5479 5480 Collective on Mat 5481 5482 Input Parameters: 5483 + mat - the matrix 5484 . perm - row and column permutation 5485 - info - structure containing 5486 $ levels - number of levels of fill. 5487 $ expected fill - as ratio of original fill. 5488 5489 Output Parameter: 5490 . fact - the factored matrix 5491 5492 Notes: 5493 Most users should employ the KSP interface for linear solvers 5494 instead of working directly with matrix algebra routines such as this. 5495 See, e.g., KSPCreate(). 5496 5497 Level: developer 5498 5499 Concepts: matrices^symbolic incomplete Cholesky factorization 5500 Concepts: matrices^factorization 5501 Concepts: Cholsky^symbolic factorization 5502 5503 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 5504 5505 Developer Note: fortran interface is not autogenerated as the f90 5506 interface defintion cannot be generated correctly [due to MatFactorInfo] 5507 5508 @*/ 5509 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat fact,Mat mat,IS perm,const MatFactorInfo *info) 5510 { 5511 PetscErrorCode ierr; 5512 5513 PetscFunctionBegin; 5514 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5515 PetscValidType(mat,1); 5516 PetscValidHeaderSpecific(perm,IS_CLASSID,2); 5517 PetscValidPointer(info,3); 5518 PetscValidPointer(fact,4); 5519 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5520 if (info->levels < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels); 5521 if (info->fill < 1.0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 5522 if (!(fact)->ops->iccfactorsymbolic) SETERRQ1(PETSC_ERR_SUP,"Matrix type %s symbolic ICC",((PetscObject)mat)->type_name); 5523 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5524 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5525 5526 ierr = PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 5527 ierr = (fact->ops->iccfactorsymbolic)(fact,mat,perm,info);CHKERRQ(ierr); 5528 ierr = PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 5529 PetscFunctionReturn(0); 5530 } 5531 5532 #undef __FUNCT__ 5533 #define __FUNCT__ "MatGetArray" 5534 /*@C 5535 MatGetArray - Returns a pointer to the element values in the matrix. 5536 The result of this routine is dependent on the underlying matrix data 5537 structure, and may not even work for certain matrix types. You MUST 5538 call MatRestoreArray() when you no longer need to access the array. 5539 5540 Not Collective 5541 5542 Input Parameter: 5543 . mat - the matrix 5544 5545 Output Parameter: 5546 . v - the location of the values 5547 5548 5549 Fortran Note: 5550 This routine is used differently from Fortran, e.g., 5551 .vb 5552 Mat mat 5553 PetscScalar mat_array(1) 5554 PetscOffset i_mat 5555 PetscErrorCode ierr 5556 call MatGetArray(mat,mat_array,i_mat,ierr) 5557 5558 C Access first local entry in matrix; note that array is 5559 C treated as one dimensional 5560 value = mat_array(i_mat + 1) 5561 5562 [... other code ...] 5563 call MatRestoreArray(mat,mat_array,i_mat,ierr) 5564 .ve 5565 5566 See the Fortran chapter of the users manual and 5567 petsc/src/mat/examples/tests for details. 5568 5569 Level: advanced 5570 5571 Concepts: matrices^access array 5572 5573 .seealso: MatRestoreArray(), MatGetArrayF90(), MatGetRowIJ() 5574 @*/ 5575 PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[]) 5576 { 5577 PetscErrorCode ierr; 5578 5579 PetscFunctionBegin; 5580 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5581 PetscValidType(mat,1); 5582 PetscValidPointer(v,2); 5583 if (!mat->ops->getarray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5584 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5585 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 5586 CHKMEMQ; 5587 PetscFunctionReturn(0); 5588 } 5589 5590 #undef __FUNCT__ 5591 #define __FUNCT__ "MatRestoreArray" 5592 /*@C 5593 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 5594 5595 Not Collective 5596 5597 Input Parameter: 5598 + mat - the matrix 5599 - v - the location of the values 5600 5601 Fortran Note: 5602 This routine is used differently from Fortran, e.g., 5603 .vb 5604 Mat mat 5605 PetscScalar mat_array(1) 5606 PetscOffset i_mat 5607 PetscErrorCode ierr 5608 call MatGetArray(mat,mat_array,i_mat,ierr) 5609 5610 C Access first local entry in matrix; note that array is 5611 C treated as one dimensional 5612 value = mat_array(i_mat + 1) 5613 5614 [... other code ...] 5615 call MatRestoreArray(mat,mat_array,i_mat,ierr) 5616 .ve 5617 5618 See the Fortran chapter of the users manual and 5619 petsc/src/mat/examples/tests for details 5620 5621 Level: advanced 5622 5623 .seealso: MatGetArray(), MatRestoreArrayF90() 5624 @*/ 5625 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[]) 5626 { 5627 PetscErrorCode ierr; 5628 5629 PetscFunctionBegin; 5630 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5631 PetscValidType(mat,1); 5632 PetscValidPointer(v,2); 5633 #if defined(PETSC_USE_DEBUG) 5634 CHKMEMQ; 5635 #endif 5636 if (!mat->ops->restorearray) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5637 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 5638 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5639 PetscFunctionReturn(0); 5640 } 5641 5642 #undef __FUNCT__ 5643 #define __FUNCT__ "MatGetSubMatrices" 5644 /*@C 5645 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 5646 points to an array of valid matrices, they may be reused to store the new 5647 submatrices. 5648 5649 Collective on Mat 5650 5651 Input Parameters: 5652 + mat - the matrix 5653 . n - the number of submatrixes to be extracted (on this processor, may be zero) 5654 . irow, icol - index sets of rows and columns to extract 5655 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5656 5657 Output Parameter: 5658 . submat - the array of submatrices 5659 5660 Notes: 5661 MatGetSubMatrices() can extract ONLY sequential submatrices 5662 (from both sequential and parallel matrices). Use MatGetSubMatrix() 5663 to extract a parallel submatrix. 5664 5665 When extracting submatrices from a parallel matrix, each processor can 5666 form a different submatrix by setting the rows and columns of its 5667 individual index sets according to the local submatrix desired. 5668 5669 When finished using the submatrices, the user should destroy 5670 them with MatDestroyMatrices(). 5671 5672 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 5673 original matrix has not changed from that last call to MatGetSubMatrices(). 5674 5675 This routine creates the matrices in submat; you should NOT create them before 5676 calling it. It also allocates the array of matrix pointers submat. 5677 5678 For BAIJ matrices the index sets must respect the block structure, that is if they 5679 request one row/column in a block, they must request all rows/columns that are in 5680 that block. For example, if the block size is 2 you cannot request just row 0 and 5681 column 0. 5682 5683 Fortran Note: 5684 The Fortran interface is slightly different from that given below; it 5685 requires one to pass in as submat a Mat (integer) array of size at least m. 5686 5687 Level: advanced 5688 5689 Concepts: matrices^accessing submatrices 5690 Concepts: submatrices 5691 5692 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal(), MatReuse 5693 @*/ 5694 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[]) 5695 { 5696 PetscErrorCode ierr; 5697 PetscInt i; 5698 PetscTruth eq; 5699 5700 PetscFunctionBegin; 5701 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5702 PetscValidType(mat,1); 5703 if (n) { 5704 PetscValidPointer(irow,3); 5705 PetscValidHeaderSpecific(*irow,IS_CLASSID,3); 5706 PetscValidPointer(icol,4); 5707 PetscValidHeaderSpecific(*icol,IS_CLASSID,4); 5708 } 5709 PetscValidPointer(submat,6); 5710 if (n && scall == MAT_REUSE_MATRIX) { 5711 PetscValidPointer(*submat,6); 5712 PetscValidHeaderSpecific(**submat,MAT_CLASSID,6); 5713 } 5714 if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5715 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5716 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5717 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5718 5719 ierr = PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 5720 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 5721 ierr = PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 5722 for (i=0; i<n; i++) { 5723 if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) { 5724 ierr = ISEqual(irow[i],icol[i],&eq);CHKERRQ(ierr); 5725 if (eq) { 5726 if (mat->symmetric){ 5727 ierr = MatSetOption((*submat)[i],MAT_SYMMETRIC,PETSC_TRUE);CHKERRQ(ierr); 5728 } else if (mat->hermitian) { 5729 ierr = MatSetOption((*submat)[i],MAT_HERMITIAN,PETSC_TRUE);CHKERRQ(ierr); 5730 } else if (mat->structurally_symmetric) { 5731 ierr = MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC,PETSC_TRUE);CHKERRQ(ierr); 5732 } 5733 } 5734 } 5735 } 5736 PetscFunctionReturn(0); 5737 } 5738 5739 #undef __FUNCT__ 5740 #define __FUNCT__ "MatDestroyMatrices" 5741 /*@C 5742 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 5743 5744 Collective on Mat 5745 5746 Input Parameters: 5747 + n - the number of local matrices 5748 - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling 5749 sequence of MatGetSubMatrices()) 5750 5751 Level: advanced 5752 5753 Notes: Frees not only the matrices, but also the array that contains the matrices 5754 In Fortran will not free the array. 5755 5756 .seealso: MatGetSubMatrices() 5757 @*/ 5758 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[]) 5759 { 5760 PetscErrorCode ierr; 5761 PetscInt i; 5762 5763 PetscFunctionBegin; 5764 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n); 5765 PetscValidPointer(mat,2); 5766 for (i=0; i<n; i++) { 5767 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 5768 } 5769 /* memory is allocated even if n = 0 */ 5770 ierr = PetscFree(*mat);CHKERRQ(ierr); 5771 PetscFunctionReturn(0); 5772 } 5773 5774 #undef __FUNCT__ 5775 #define __FUNCT__ "MatGetSeqNonzeroStructure" 5776 /*@C 5777 MatGetSeqNonzeroStructure - Extracts the sequential nonzero structure from a matrix. 5778 5779 Collective on Mat 5780 5781 Input Parameters: 5782 . mat - the matrix 5783 5784 Output Parameter: 5785 . matstruct - the sequential matrix with the nonzero structure of mat 5786 5787 Level: intermediate 5788 5789 .seealso: MatDestroySeqNonzeroStructure(), MatGetSubMatrices(), MatDestroyMatrices() 5790 @*/ 5791 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSeqNonzeroStructure(Mat mat,Mat *matstruct) 5792 { 5793 PetscErrorCode ierr; 5794 5795 PetscFunctionBegin; 5796 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5797 PetscValidPointer(matstruct,2); 5798 5799 PetscValidType(mat,1); 5800 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5801 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5802 5803 if (!mat->ops->getseqnonzerostructure) SETERRQ1(PETSC_ERR_SUP,"Not for matrix type %s\n",((PetscObject)mat)->type_name); 5804 ierr = PetscLogEventBegin(MAT_GetSeqNonzeroStructure,mat,0,0,0);CHKERRQ(ierr); 5805 ierr = (*mat->ops->getseqnonzerostructure)(mat,matstruct);CHKERRQ(ierr); 5806 ierr = PetscLogEventEnd(MAT_GetSeqNonzeroStructure,mat,0,0,0);CHKERRQ(ierr); 5807 PetscFunctionReturn(0); 5808 } 5809 5810 #undef __FUNCT__ 5811 #define __FUNCT__ "MatDestroySeqNonzeroStructure" 5812 /*@C 5813 MatDestroySeqNonzeroStructure - Destroys matrix obtained with MatGetSeqNonzeroStructure(). 5814 5815 Collective on Mat 5816 5817 Input Parameters: 5818 . mat - the matrix (note that this is a pointer to the array of matrices, just to match the calling 5819 sequence of MatGetSequentialNonzeroStructure()) 5820 5821 Level: advanced 5822 5823 Notes: Frees not only the matrices, but also the array that contains the matrices 5824 5825 .seealso: MatGetSeqNonzeroStructure() 5826 @*/ 5827 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroySeqNonzeroStructure(Mat *mat) 5828 { 5829 PetscErrorCode ierr; 5830 5831 PetscFunctionBegin; 5832 PetscValidPointer(mat,1); 5833 ierr = MatDestroy(*mat);CHKERRQ(ierr); 5834 PetscFunctionReturn(0); 5835 } 5836 5837 #undef __FUNCT__ 5838 #define __FUNCT__ "MatIncreaseOverlap" 5839 /*@ 5840 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 5841 replaces the index sets by larger ones that represent submatrices with 5842 additional overlap. 5843 5844 Collective on Mat 5845 5846 Input Parameters: 5847 + mat - the matrix 5848 . n - the number of index sets 5849 . is - the array of index sets (these index sets will changed during the call) 5850 - ov - the additional overlap requested 5851 5852 Level: developer 5853 5854 Concepts: overlap 5855 Concepts: ASM^computing overlap 5856 5857 .seealso: MatGetSubMatrices() 5858 @*/ 5859 PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov) 5860 { 5861 PetscErrorCode ierr; 5862 5863 PetscFunctionBegin; 5864 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5865 PetscValidType(mat,1); 5866 if (n < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n); 5867 if (n) { 5868 PetscValidPointer(is,3); 5869 PetscValidHeaderSpecific(*is,IS_CLASSID,3); 5870 } 5871 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5872 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5873 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5874 5875 if (!ov) PetscFunctionReturn(0); 5876 if (!mat->ops->increaseoverlap) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5877 ierr = PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 5878 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 5879 ierr = PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 5880 PetscFunctionReturn(0); 5881 } 5882 5883 #undef __FUNCT__ 5884 #define __FUNCT__ "MatGetBlockSize" 5885 /*@ 5886 MatGetBlockSize - Returns the matrix block size; useful especially for the 5887 block row and block diagonal formats. 5888 5889 Not Collective 5890 5891 Input Parameter: 5892 . mat - the matrix 5893 5894 Output Parameter: 5895 . bs - block size 5896 5897 Notes: 5898 Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ 5899 5900 Level: intermediate 5901 5902 Concepts: matrices^block size 5903 5904 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ() 5905 @*/ 5906 PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs) 5907 { 5908 PetscErrorCode ierr; 5909 5910 PetscFunctionBegin; 5911 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5912 PetscValidType(mat,1); 5913 PetscValidIntPointer(bs,2); 5914 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5915 *bs = mat->rmap->bs; 5916 PetscFunctionReturn(0); 5917 } 5918 5919 #undef __FUNCT__ 5920 #define __FUNCT__ "MatSetBlockSize" 5921 /*@ 5922 MatSetBlockSize - Sets the matrix block size; for many matrix types you 5923 cannot use this and MUST set the blocksize when you preallocate the matrix 5924 5925 Collective on Mat 5926 5927 Input Parameters: 5928 + mat - the matrix 5929 - bs - block size 5930 5931 Notes: 5932 For BAIJ matrices, this just checks that the block size agrees with the BAIJ size, 5933 it is not possible to change BAIJ block sizes after preallocation. 5934 5935 Level: intermediate 5936 5937 Concepts: matrices^block size 5938 5939 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatGetBlockSize() 5940 @*/ 5941 PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs) 5942 { 5943 PetscErrorCode ierr; 5944 5945 PetscFunctionBegin; 5946 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5947 PetscValidType(mat,1); 5948 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5949 if (bs < 1) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Block size %d, must be positive",bs); 5950 if (mat->ops->setblocksize) { 5951 ierr = (*mat->ops->setblocksize)(mat,bs);CHKERRQ(ierr); 5952 } else { 5953 SETERRQ1(PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",((PetscObject)mat)->type_name); 5954 } 5955 PetscFunctionReturn(0); 5956 } 5957 5958 #undef __FUNCT__ 5959 #define __FUNCT__ "MatGetRowIJ" 5960 /*@C 5961 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 5962 5963 Collective on Mat 5964 5965 Input Parameters: 5966 + mat - the matrix 5967 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 5968 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 5969 symmetrized 5970 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 5971 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 5972 always used. 5973 5974 Output Parameters: 5975 + n - number of rows in the (possibly compressed) matrix 5976 . ia - the row pointers [of length n+1] 5977 . ja - the column indices 5978 - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers 5979 are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set 5980 5981 Level: developer 5982 5983 Notes: You CANNOT change any of the ia[] or ja[] values. 5984 5985 Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values 5986 5987 Fortran Node 5988 5989 In Fortran use 5990 $ PetscInt ia(1), ja(1) 5991 $ PetscOffset iia, jja 5992 $ call MatGetRowIJ(mat,shift,symmetric,inodecompressed,n,ia,iia,ja,jja,done,ierr) 5993 $ 5994 $ or 5995 $ 5996 $ PetscScalar, pointer :: xx_v(:) 5997 $ call MatGetRowIJF90(mat,shift,symmetric,inodecompressed,n,ia,ja,done,ierr) 5998 5999 6000 Acess the ith and jth entries via ia(iia + i) and ja(jja + j) 6001 6002 .seealso: MatGetColumnIJ(), MatRestoreRowIJ(), MatGetArray() 6003 @*/ 6004 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6005 { 6006 PetscErrorCode ierr; 6007 6008 PetscFunctionBegin; 6009 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6010 PetscValidType(mat,1); 6011 PetscValidIntPointer(n,4); 6012 if (ia) PetscValidIntPointer(ia,5); 6013 if (ja) PetscValidIntPointer(ja,6); 6014 PetscValidIntPointer(done,7); 6015 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6016 if (!mat->ops->getrowij) *done = PETSC_FALSE; 6017 else { 6018 *done = PETSC_TRUE; 6019 ierr = PetscLogEventBegin(MAT_GetRowIJ,mat,0,0,0);CHKERRQ(ierr); 6020 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6021 ierr = PetscLogEventEnd(MAT_GetRowIJ,mat,0,0,0);CHKERRQ(ierr); 6022 } 6023 PetscFunctionReturn(0); 6024 } 6025 6026 #undef __FUNCT__ 6027 #define __FUNCT__ "MatGetColumnIJ" 6028 /*@C 6029 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 6030 6031 Collective on Mat 6032 6033 Input Parameters: 6034 + mat - the matrix 6035 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6036 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6037 symmetrized 6038 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6039 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6040 always used. 6041 6042 Output Parameters: 6043 + n - number of columns in the (possibly compressed) matrix 6044 . ia - the column pointers 6045 . ja - the row indices 6046 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 6047 6048 Level: developer 6049 6050 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 6051 @*/ 6052 PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6053 { 6054 PetscErrorCode ierr; 6055 6056 PetscFunctionBegin; 6057 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6058 PetscValidType(mat,1); 6059 PetscValidIntPointer(n,4); 6060 if (ia) PetscValidIntPointer(ia,5); 6061 if (ja) PetscValidIntPointer(ja,6); 6062 PetscValidIntPointer(done,7); 6063 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6064 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 6065 else { 6066 *done = PETSC_TRUE; 6067 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6068 } 6069 PetscFunctionReturn(0); 6070 } 6071 6072 #undef __FUNCT__ 6073 #define __FUNCT__ "MatRestoreRowIJ" 6074 /*@C 6075 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 6076 MatGetRowIJ(). 6077 6078 Collective on Mat 6079 6080 Input Parameters: 6081 + mat - the matrix 6082 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6083 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6084 symmetrized 6085 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6086 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6087 always used. 6088 6089 Output Parameters: 6090 + n - size of (possibly compressed) matrix 6091 . ia - the row pointers 6092 . ja - the column indices 6093 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 6094 6095 Level: developer 6096 6097 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 6098 @*/ 6099 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6100 { 6101 PetscErrorCode ierr; 6102 6103 PetscFunctionBegin; 6104 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6105 PetscValidType(mat,1); 6106 if (ia) PetscValidIntPointer(ia,5); 6107 if (ja) PetscValidIntPointer(ja,6); 6108 PetscValidIntPointer(done,7); 6109 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6110 6111 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 6112 else { 6113 *done = PETSC_TRUE; 6114 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6115 } 6116 PetscFunctionReturn(0); 6117 } 6118 6119 #undef __FUNCT__ 6120 #define __FUNCT__ "MatRestoreColumnIJ" 6121 /*@C 6122 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 6123 MatGetColumnIJ(). 6124 6125 Collective on Mat 6126 6127 Input Parameters: 6128 + mat - the matrix 6129 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6130 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6131 symmetrized 6132 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6133 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6134 always used. 6135 6136 Output Parameters: 6137 + n - size of (possibly compressed) matrix 6138 . ia - the column pointers 6139 . ja - the row indices 6140 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 6141 6142 Level: developer 6143 6144 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 6145 @*/ 6146 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6147 { 6148 PetscErrorCode ierr; 6149 6150 PetscFunctionBegin; 6151 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6152 PetscValidType(mat,1); 6153 if (ia) PetscValidIntPointer(ia,5); 6154 if (ja) PetscValidIntPointer(ja,6); 6155 PetscValidIntPointer(done,7); 6156 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6157 6158 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 6159 else { 6160 *done = PETSC_TRUE; 6161 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6162 } 6163 PetscFunctionReturn(0); 6164 } 6165 6166 #undef __FUNCT__ 6167 #define __FUNCT__ "MatColoringPatch" 6168 /*@C 6169 MatColoringPatch -Used inside matrix coloring routines that 6170 use MatGetRowIJ() and/or MatGetColumnIJ(). 6171 6172 Collective on Mat 6173 6174 Input Parameters: 6175 + mat - the matrix 6176 . ncolors - max color value 6177 . n - number of entries in colorarray 6178 - colorarray - array indicating color for each column 6179 6180 Output Parameters: 6181 . iscoloring - coloring generated using colorarray information 6182 6183 Level: developer 6184 6185 .seealso: MatGetRowIJ(), MatGetColumnIJ() 6186 6187 @*/ 6188 PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring) 6189 { 6190 PetscErrorCode ierr; 6191 6192 PetscFunctionBegin; 6193 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6194 PetscValidType(mat,1); 6195 PetscValidIntPointer(colorarray,4); 6196 PetscValidPointer(iscoloring,5); 6197 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6198 6199 if (!mat->ops->coloringpatch){ 6200 ierr = ISColoringCreate(((PetscObject)mat)->comm,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 6201 } else { 6202 ierr = (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 6203 } 6204 PetscFunctionReturn(0); 6205 } 6206 6207 6208 #undef __FUNCT__ 6209 #define __FUNCT__ "MatSetUnfactored" 6210 /*@ 6211 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 6212 6213 Collective on Mat 6214 6215 Input Parameter: 6216 . mat - the factored matrix to be reset 6217 6218 Notes: 6219 This routine should be used only with factored matrices formed by in-place 6220 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 6221 format). This option can save memory, for example, when solving nonlinear 6222 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 6223 ILU(0) preconditioner. 6224 6225 Note that one can specify in-place ILU(0) factorization by calling 6226 .vb 6227 PCType(pc,PCILU); 6228 PCFactorSeUseInPlace(pc); 6229 .ve 6230 or by using the options -pc_type ilu -pc_factor_in_place 6231 6232 In-place factorization ILU(0) can also be used as a local 6233 solver for the blocks within the block Jacobi or additive Schwarz 6234 methods (runtime option: -sub_pc_factor_in_place). See the discussion 6235 of these preconditioners in the users manual for details on setting 6236 local solver options. 6237 6238 Most users should employ the simplified KSP interface for linear solvers 6239 instead of working directly with matrix algebra routines such as this. 6240 See, e.g., KSPCreate(). 6241 6242 Level: developer 6243 6244 .seealso: PCFactorSetUseInPlace() 6245 6246 Concepts: matrices^unfactored 6247 6248 @*/ 6249 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat) 6250 { 6251 PetscErrorCode ierr; 6252 6253 PetscFunctionBegin; 6254 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6255 PetscValidType(mat,1); 6256 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6257 mat->factortype = MAT_FACTOR_NONE; 6258 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 6259 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 6260 PetscFunctionReturn(0); 6261 } 6262 6263 /*MC 6264 MatGetArrayF90 - Accesses a matrix array from Fortran90. 6265 6266 Synopsis: 6267 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 6268 6269 Not collective 6270 6271 Input Parameter: 6272 . x - matrix 6273 6274 Output Parameters: 6275 + xx_v - the Fortran90 pointer to the array 6276 - ierr - error code 6277 6278 Example of Usage: 6279 .vb 6280 PetscScalar, pointer xx_v(:) 6281 .... 6282 call MatGetArrayF90(x,xx_v,ierr) 6283 a = xx_v(3) 6284 call MatRestoreArrayF90(x,xx_v,ierr) 6285 .ve 6286 6287 Notes: 6288 Not yet supported for all F90 compilers 6289 6290 Level: advanced 6291 6292 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 6293 6294 Concepts: matrices^accessing array 6295 6296 M*/ 6297 6298 /*MC 6299 MatRestoreArrayF90 - Restores a matrix array that has been 6300 accessed with MatGetArrayF90(). 6301 6302 Synopsis: 6303 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 6304 6305 Not collective 6306 6307 Input Parameters: 6308 + x - matrix 6309 - xx_v - the Fortran90 pointer to the array 6310 6311 Output Parameter: 6312 . ierr - error code 6313 6314 Example of Usage: 6315 .vb 6316 PetscScalar, pointer xx_v(:) 6317 .... 6318 call MatGetArrayF90(x,xx_v,ierr) 6319 a = xx_v(3) 6320 call MatRestoreArrayF90(x,xx_v,ierr) 6321 .ve 6322 6323 Notes: 6324 Not yet supported for all F90 compilers 6325 6326 Level: advanced 6327 6328 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 6329 6330 M*/ 6331 6332 6333 #undef __FUNCT__ 6334 #define __FUNCT__ "MatGetSubMatrix" 6335 /*@ 6336 MatGetSubMatrix - Gets a single submatrix on the same number of processors 6337 as the original matrix. 6338 6339 Collective on Mat 6340 6341 Input Parameters: 6342 + mat - the original matrix 6343 . isrow - parallel IS containing the rows this processor should obtain 6344 . 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. 6345 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6346 6347 Output Parameter: 6348 . newmat - the new submatrix, of the same type as the old 6349 6350 Level: advanced 6351 6352 Notes: 6353 The submatrix will be able to be multiplied with vectors using the same layout as iscol. 6354 6355 The rows in isrow will be sorted into the same order as the original matrix on each process. 6356 6357 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 6358 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 6359 to this routine with a mat of the same nonzero structure and with a call of MAT_REUSE_MATRIX 6360 will reuse the matrix generated the first time. You should call MatDestroy() on newmat when 6361 you are finished using it. 6362 6363 The communicator of the newly obtained matrix is ALWAYS the same as the communicator of 6364 the input matrix. 6365 6366 If iscol is PETSC_NULL then all columns are obtained (not supported in Fortran). 6367 6368 Example usage: 6369 Consider the following 8x8 matrix with 34 non-zero values, that is 6370 assembled across 3 processors. Lets assume that proc0 owns 3 rows, 6371 proc1 owns 3 rows, proc2 owns 2 rows. This division can be shown 6372 as follows: 6373 6374 .vb 6375 1 2 0 | 0 3 0 | 0 4 6376 Proc0 0 5 6 | 7 0 0 | 8 0 6377 9 0 10 | 11 0 0 | 12 0 6378 ------------------------------------- 6379 13 0 14 | 15 16 17 | 0 0 6380 Proc1 0 18 0 | 19 20 21 | 0 0 6381 0 0 0 | 22 23 0 | 24 0 6382 ------------------------------------- 6383 Proc2 25 26 27 | 0 0 28 | 29 0 6384 30 0 0 | 31 32 33 | 0 34 6385 .ve 6386 6387 Suppose isrow = [0 1 | 4 | 5 6] and iscol = [1 2 | 3 4 5 | 6]. The resulting submatrix is 6388 6389 .vb 6390 2 0 | 0 3 0 | 0 6391 Proc0 5 6 | 7 0 0 | 8 6392 ------------------------------- 6393 Proc1 18 0 | 19 20 21 | 0 6394 ------------------------------- 6395 Proc2 26 27 | 0 0 28 | 29 6396 0 0 | 31 32 33 | 0 6397 .ve 6398 6399 6400 Concepts: matrices^submatrices 6401 6402 .seealso: MatGetSubMatrices() 6403 @*/ 6404 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,MatReuse cll,Mat *newmat) 6405 { 6406 PetscErrorCode ierr; 6407 PetscMPIInt size; 6408 Mat *local; 6409 IS iscoltmp; 6410 6411 PetscFunctionBegin; 6412 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6413 PetscValidHeaderSpecific(isrow,IS_CLASSID,2); 6414 if (iscol) PetscValidHeaderSpecific(iscol,IS_CLASSID,3); 6415 PetscValidPointer(newmat,5); 6416 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_CLASSID,5); 6417 PetscValidType(mat,1); 6418 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6419 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6420 ierr = MPI_Comm_size(((PetscObject)mat)->comm,&size);CHKERRQ(ierr); 6421 6422 if (!iscol) { 6423 ierr = ISCreateStride(((PetscObject)mat)->comm,mat->cmap->n,mat->cmap->rstart,1,&iscoltmp);CHKERRQ(ierr); 6424 } else { 6425 iscoltmp = iscol; 6426 } 6427 6428 /* if original matrix is on just one processor then use submatrix generated */ 6429 if (mat->ops->getsubmatrices && !mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 6430 ierr = MatGetSubMatrices(mat,1,&isrow,&iscoltmp,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 6431 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6432 PetscFunctionReturn(0); 6433 } else if (mat->ops->getsubmatrices && !mat->ops->getsubmatrix && size == 1) { 6434 ierr = MatGetSubMatrices(mat,1,&isrow,&iscoltmp,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 6435 *newmat = *local; 6436 ierr = PetscFree(local);CHKERRQ(ierr); 6437 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6438 PetscFunctionReturn(0); 6439 } else if (!mat->ops->getsubmatrix) { 6440 /* Create a new matrix type that implements the operation using the full matrix */ 6441 switch (cll) { 6442 case MAT_INITIAL_MATRIX: 6443 ierr = MatCreateSubMatrix(mat,isrow,iscoltmp,newmat);CHKERRQ(ierr); 6444 break; 6445 case MAT_REUSE_MATRIX: 6446 ierr = MatSubMatrixUpdate(*newmat,mat,isrow,iscoltmp);CHKERRQ(ierr); 6447 break; 6448 default: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid MatReuse, must be either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX"); 6449 } 6450 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6451 PetscFunctionReturn(0); 6452 } 6453 6454 if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6455 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscoltmp,cll,newmat);CHKERRQ(ierr); 6456 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6457 ierr = PetscObjectStateIncrease((PetscObject)*newmat);CHKERRQ(ierr); 6458 PetscFunctionReturn(0); 6459 } 6460 6461 #undef __FUNCT__ 6462 #define __FUNCT__ "MatStashSetInitialSize" 6463 /*@ 6464 MatStashSetInitialSize - sets the sizes of the matrix stash, that is 6465 used during the assembly process to store values that belong to 6466 other processors. 6467 6468 Not Collective 6469 6470 Input Parameters: 6471 + mat - the matrix 6472 . size - the initial size of the stash. 6473 - bsize - the initial size of the block-stash(if used). 6474 6475 Options Database Keys: 6476 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 6477 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 6478 6479 Level: intermediate 6480 6481 Notes: 6482 The block-stash is used for values set with MatSetValuesBlocked() while 6483 the stash is used for values set with MatSetValues() 6484 6485 Run with the option -info and look for output of the form 6486 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 6487 to determine the appropriate value, MM, to use for size and 6488 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 6489 to determine the value, BMM to use for bsize 6490 6491 Concepts: stash^setting matrix size 6492 Concepts: matrices^stash 6493 6494 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashGetInfo() 6495 6496 @*/ 6497 PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize) 6498 { 6499 PetscErrorCode ierr; 6500 6501 PetscFunctionBegin; 6502 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6503 PetscValidType(mat,1); 6504 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 6505 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 6506 PetscFunctionReturn(0); 6507 } 6508 6509 #undef __FUNCT__ 6510 #define __FUNCT__ "MatInterpolateAdd" 6511 /*@ 6512 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 6513 the matrix 6514 6515 Collective on Mat 6516 6517 Input Parameters: 6518 + mat - the matrix 6519 . x,y - the vectors 6520 - w - where the result is stored 6521 6522 Level: intermediate 6523 6524 Notes: 6525 w may be the same vector as y. 6526 6527 This allows one to use either the restriction or interpolation (its transpose) 6528 matrix to do the interpolation 6529 6530 Concepts: interpolation 6531 6532 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 6533 6534 @*/ 6535 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 6536 { 6537 PetscErrorCode ierr; 6538 PetscInt M,N; 6539 6540 PetscFunctionBegin; 6541 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6542 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6543 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6544 PetscValidHeaderSpecific(w,VEC_CLASSID,4); 6545 PetscValidType(A,1); 6546 ierr = MatPreallocated(A);CHKERRQ(ierr); 6547 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6548 if (N > M) { 6549 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 6550 } else { 6551 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 6552 } 6553 PetscFunctionReturn(0); 6554 } 6555 6556 #undef __FUNCT__ 6557 #define __FUNCT__ "MatInterpolate" 6558 /*@ 6559 MatInterpolate - y = A*x or A'*x depending on the shape of 6560 the matrix 6561 6562 Collective on Mat 6563 6564 Input Parameters: 6565 + mat - the matrix 6566 - x,y - the vectors 6567 6568 Level: intermediate 6569 6570 Notes: 6571 This allows one to use either the restriction or interpolation (its transpose) 6572 matrix to do the interpolation 6573 6574 Concepts: matrices^interpolation 6575 6576 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 6577 6578 @*/ 6579 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y) 6580 { 6581 PetscErrorCode ierr; 6582 PetscInt M,N; 6583 6584 PetscFunctionBegin; 6585 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6586 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6587 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6588 PetscValidType(A,1); 6589 ierr = MatPreallocated(A);CHKERRQ(ierr); 6590 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6591 if (N > M) { 6592 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 6593 } else { 6594 ierr = MatMult(A,x,y);CHKERRQ(ierr); 6595 } 6596 PetscFunctionReturn(0); 6597 } 6598 6599 #undef __FUNCT__ 6600 #define __FUNCT__ "MatRestrict" 6601 /*@ 6602 MatRestrict - y = A*x or A'*x 6603 6604 Collective on Mat 6605 6606 Input Parameters: 6607 + mat - the matrix 6608 - x,y - the vectors 6609 6610 Level: intermediate 6611 6612 Notes: 6613 This allows one to use either the restriction or interpolation (its transpose) 6614 matrix to do the restriction 6615 6616 Concepts: matrices^restriction 6617 6618 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 6619 6620 @*/ 6621 PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y) 6622 { 6623 PetscErrorCode ierr; 6624 PetscInt M,N; 6625 6626 PetscFunctionBegin; 6627 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6628 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6629 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6630 PetscValidType(A,1); 6631 ierr = MatPreallocated(A);CHKERRQ(ierr); 6632 6633 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6634 if (N > M) { 6635 ierr = MatMult(A,x,y);CHKERRQ(ierr); 6636 } else { 6637 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 6638 } 6639 PetscFunctionReturn(0); 6640 } 6641 6642 #undef __FUNCT__ 6643 #define __FUNCT__ "MatNullSpaceAttach" 6644 /*@ 6645 MatNullSpaceAttach - attaches a null space to a matrix. 6646 This null space will be removed from the resulting vector whenever 6647 MatMult() is called 6648 6649 Collective on Mat 6650 6651 Input Parameters: 6652 + mat - the matrix 6653 - nullsp - the null space object 6654 6655 Level: developer 6656 6657 Notes: 6658 Overwrites any previous null space that may have been attached 6659 6660 Concepts: null space^attaching to matrix 6661 6662 .seealso: MatCreate(), MatNullSpaceCreate() 6663 @*/ 6664 PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 6665 { 6666 PetscErrorCode ierr; 6667 6668 PetscFunctionBegin; 6669 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6670 PetscValidType(mat,1); 6671 PetscValidHeaderSpecific(nullsp,MAT_NULLSPACE_CLASSID,2); 6672 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6673 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 6674 if (mat->nullsp) { ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); } 6675 mat->nullsp = nullsp; 6676 PetscFunctionReturn(0); 6677 } 6678 6679 #undef __FUNCT__ 6680 #define __FUNCT__ "MatICCFactor" 6681 /*@C 6682 MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix. 6683 6684 Collective on Mat 6685 6686 Input Parameters: 6687 + mat - the matrix 6688 . row - row/column permutation 6689 . fill - expected fill factor >= 1.0 6690 - level - level of fill, for ICC(k) 6691 6692 Notes: 6693 Probably really in-place only when level of fill is zero, otherwise allocates 6694 new space to store factored matrix and deletes previous memory. 6695 6696 Most users should employ the simplified KSP interface for linear solvers 6697 instead of working directly with matrix algebra routines such as this. 6698 See, e.g., KSPCreate(). 6699 6700 Level: developer 6701 6702 Concepts: matrices^incomplete Cholesky factorization 6703 Concepts: Cholesky factorization 6704 6705 .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 6706 6707 Developer Note: fortran interface is not autogenerated as the f90 6708 interface defintion cannot be generated correctly [due to MatFactorInfo] 6709 6710 @*/ 6711 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,const MatFactorInfo* info) 6712 { 6713 PetscErrorCode ierr; 6714 6715 PetscFunctionBegin; 6716 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6717 PetscValidType(mat,1); 6718 if (row) PetscValidHeaderSpecific(row,IS_CLASSID,2); 6719 PetscValidPointer(info,3); 6720 if (mat->rmap->N != mat->cmap->N) SETERRQ(PETSC_ERR_ARG_WRONG,"matrix must be square"); 6721 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6722 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6723 if (!mat->ops->iccfactor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6724 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6725 ierr = (*mat->ops->iccfactor)(mat,row,info);CHKERRQ(ierr); 6726 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6727 PetscFunctionReturn(0); 6728 } 6729 6730 #undef __FUNCT__ 6731 #define __FUNCT__ "MatSetValuesAdic" 6732 /*@ 6733 MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix. 6734 6735 Not Collective 6736 6737 Input Parameters: 6738 + mat - the matrix 6739 - v - the values compute with ADIC 6740 6741 Level: developer 6742 6743 Notes: 6744 Must call MatSetColoring() before using this routine. Also this matrix must already 6745 have its nonzero pattern determined. 6746 6747 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6748 MatSetValues(), MatSetColoring(), MatSetValuesAdifor() 6749 @*/ 6750 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v) 6751 { 6752 PetscErrorCode ierr; 6753 6754 PetscFunctionBegin; 6755 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6756 PetscValidType(mat,1); 6757 PetscValidPointer(mat,2); 6758 6759 if (!mat->assembled) { 6760 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6761 } 6762 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6763 if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6764 ierr = (*mat->ops->setvaluesadic)(mat,v);CHKERRQ(ierr); 6765 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6766 ierr = MatView_Private(mat);CHKERRQ(ierr); 6767 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6768 PetscFunctionReturn(0); 6769 } 6770 6771 6772 #undef __FUNCT__ 6773 #define __FUNCT__ "MatSetColoring" 6774 /*@ 6775 MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic() 6776 6777 Not Collective 6778 6779 Input Parameters: 6780 + mat - the matrix 6781 - coloring - the coloring 6782 6783 Level: developer 6784 6785 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6786 MatSetValues(), MatSetValuesAdic() 6787 @*/ 6788 PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring) 6789 { 6790 PetscErrorCode ierr; 6791 6792 PetscFunctionBegin; 6793 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6794 PetscValidType(mat,1); 6795 PetscValidPointer(coloring,2); 6796 6797 if (!mat->assembled) { 6798 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6799 } 6800 if (!mat->ops->setcoloring) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6801 ierr = (*mat->ops->setcoloring)(mat,coloring);CHKERRQ(ierr); 6802 PetscFunctionReturn(0); 6803 } 6804 6805 #undef __FUNCT__ 6806 #define __FUNCT__ "MatSetValuesAdifor" 6807 /*@ 6808 MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix. 6809 6810 Not Collective 6811 6812 Input Parameters: 6813 + mat - the matrix 6814 . nl - leading dimension of v 6815 - v - the values compute with ADIFOR 6816 6817 Level: developer 6818 6819 Notes: 6820 Must call MatSetColoring() before using this routine. Also this matrix must already 6821 have its nonzero pattern determined. 6822 6823 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6824 MatSetValues(), MatSetColoring() 6825 @*/ 6826 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v) 6827 { 6828 PetscErrorCode ierr; 6829 6830 PetscFunctionBegin; 6831 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6832 PetscValidType(mat,1); 6833 PetscValidPointer(v,3); 6834 6835 if (!mat->assembled) { 6836 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6837 } 6838 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6839 if (!mat->ops->setvaluesadifor) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6840 ierr = (*mat->ops->setvaluesadifor)(mat,nl,v);CHKERRQ(ierr); 6841 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6842 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6843 PetscFunctionReturn(0); 6844 } 6845 6846 #undef __FUNCT__ 6847 #define __FUNCT__ "MatDiagonalScaleLocal" 6848 /*@ 6849 MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 6850 ghosted ones. 6851 6852 Not Collective 6853 6854 Input Parameters: 6855 + mat - the matrix 6856 - diag = the diagonal values, including ghost ones 6857 6858 Level: developer 6859 6860 Notes: Works only for MPIAIJ and MPIBAIJ matrices 6861 6862 .seealso: MatDiagonalScale() 6863 @*/ 6864 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag) 6865 { 6866 PetscErrorCode ierr; 6867 PetscMPIInt size; 6868 6869 PetscFunctionBegin; 6870 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6871 PetscValidHeaderSpecific(diag,VEC_CLASSID,2); 6872 PetscValidType(mat,1); 6873 6874 if (!mat->assembled) { 6875 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6876 } 6877 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 6878 ierr = MPI_Comm_size(((PetscObject)mat)->comm,&size);CHKERRQ(ierr); 6879 if (size == 1) { 6880 PetscInt n,m; 6881 ierr = VecGetSize(diag,&n);CHKERRQ(ierr); 6882 ierr = MatGetSize(mat,0,&m);CHKERRQ(ierr); 6883 if (m == n) { 6884 ierr = MatDiagonalScale(mat,0,diag);CHKERRQ(ierr); 6885 } else { 6886 SETERRQ(PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions"); 6887 } 6888 } else { 6889 PetscErrorCode (*f)(Mat,Vec); 6890 ierr = PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);CHKERRQ(ierr); 6891 if (f) { 6892 ierr = (*f)(mat,diag);CHKERRQ(ierr); 6893 } else { 6894 SETERRQ(PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices"); 6895 } 6896 } 6897 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 6898 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6899 PetscFunctionReturn(0); 6900 } 6901 6902 #undef __FUNCT__ 6903 #define __FUNCT__ "MatGetInertia" 6904 /*@ 6905 MatGetInertia - Gets the inertia from a factored matrix 6906 6907 Collective on Mat 6908 6909 Input Parameter: 6910 . mat - the matrix 6911 6912 Output Parameters: 6913 + nneg - number of negative eigenvalues 6914 . nzero - number of zero eigenvalues 6915 - npos - number of positive eigenvalues 6916 6917 Level: advanced 6918 6919 Notes: Matrix must have been factored by MatCholeskyFactor() 6920 6921 6922 @*/ 6923 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos) 6924 { 6925 PetscErrorCode ierr; 6926 6927 PetscFunctionBegin; 6928 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6929 PetscValidType(mat,1); 6930 if (!mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 6931 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled"); 6932 if (!mat->ops->getinertia) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6933 ierr = (*mat->ops->getinertia)(mat,nneg,nzero,npos);CHKERRQ(ierr); 6934 PetscFunctionReturn(0); 6935 } 6936 6937 /* ----------------------------------------------------------------*/ 6938 #undef __FUNCT__ 6939 #define __FUNCT__ "MatSolves" 6940 /*@C 6941 MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors 6942 6943 Collective on Mat and Vecs 6944 6945 Input Parameters: 6946 + mat - the factored matrix 6947 - b - the right-hand-side vectors 6948 6949 Output Parameter: 6950 . x - the result vectors 6951 6952 Notes: 6953 The vectors b and x cannot be the same. I.e., one cannot 6954 call MatSolves(A,x,x). 6955 6956 Notes: 6957 Most users should employ the simplified KSP interface for linear solvers 6958 instead of working directly with matrix algebra routines such as this. 6959 See, e.g., KSPCreate(). 6960 6961 Level: developer 6962 6963 Concepts: matrices^triangular solves 6964 6965 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve() 6966 @*/ 6967 PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x) 6968 { 6969 PetscErrorCode ierr; 6970 6971 PetscFunctionBegin; 6972 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6973 PetscValidType(mat,1); 6974 if (x == b) SETERRQ(PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 6975 if (!mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 6976 if (!mat->rmap->N && !mat->cmap->N) PetscFunctionReturn(0); 6977 6978 if (!mat->ops->solves) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6979 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6980 ierr = PetscLogEventBegin(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6981 ierr = (*mat->ops->solves)(mat,b,x);CHKERRQ(ierr); 6982 ierr = PetscLogEventEnd(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 6983 PetscFunctionReturn(0); 6984 } 6985 6986 #undef __FUNCT__ 6987 #define __FUNCT__ "MatIsSymmetric" 6988 /*@ 6989 MatIsSymmetric - Test whether a matrix is symmetric 6990 6991 Collective on Mat 6992 6993 Input Parameter: 6994 + A - the matrix to test 6995 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose) 6996 6997 Output Parameters: 6998 . flg - the result 6999 7000 Level: intermediate 7001 7002 Concepts: matrix^symmetry 7003 7004 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 7005 @*/ 7006 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg) 7007 { 7008 PetscErrorCode ierr; 7009 7010 PetscFunctionBegin; 7011 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7012 PetscValidPointer(flg,2); 7013 7014 if (!A->symmetric_set) { 7015 if (!A->ops->issymmetric) { 7016 const MatType mattype; 7017 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7018 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 7019 } 7020 ierr = (*A->ops->issymmetric)(A,tol,flg);CHKERRQ(ierr); 7021 if (!tol) { 7022 A->symmetric_set = PETSC_TRUE; 7023 A->symmetric = *flg; 7024 if (A->symmetric) { 7025 A->structurally_symmetric_set = PETSC_TRUE; 7026 A->structurally_symmetric = PETSC_TRUE; 7027 } 7028 } 7029 } else if (A->symmetric) { 7030 *flg = PETSC_TRUE; 7031 } else if (!tol) { 7032 *flg = PETSC_FALSE; 7033 } else { 7034 if (!A->ops->issymmetric) { 7035 const MatType mattype; 7036 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7037 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 7038 } 7039 ierr = (*A->ops->issymmetric)(A,tol,flg);CHKERRQ(ierr); 7040 } 7041 PetscFunctionReturn(0); 7042 } 7043 7044 #undef __FUNCT__ 7045 #define __FUNCT__ "MatIsHermitian" 7046 /*@ 7047 MatIsHermitian - Test whether a matrix is Hermitian 7048 7049 Collective on Mat 7050 7051 Input Parameter: 7052 + A - the matrix to test 7053 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact Hermitian) 7054 7055 Output Parameters: 7056 . flg - the result 7057 7058 Level: intermediate 7059 7060 Concepts: matrix^symmetry 7061 7062 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 7063 @*/ 7064 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscReal tol,PetscTruth *flg) 7065 { 7066 PetscErrorCode ierr; 7067 7068 PetscFunctionBegin; 7069 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7070 PetscValidPointer(flg,2); 7071 7072 if (!A->hermitian_set) { 7073 if (!A->ops->ishermitian) { 7074 const MatType mattype; 7075 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7076 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for hermitian",mattype); 7077 } 7078 ierr = (*A->ops->ishermitian)(A,tol,flg);CHKERRQ(ierr); 7079 if (!tol) { 7080 A->hermitian_set = PETSC_TRUE; 7081 A->hermitian = *flg; 7082 if (A->hermitian) { 7083 A->structurally_symmetric_set = PETSC_TRUE; 7084 A->structurally_symmetric = PETSC_TRUE; 7085 } 7086 } 7087 } else if (A->hermitian) { 7088 *flg = PETSC_TRUE; 7089 } else if (!tol) { 7090 *flg = PETSC_FALSE; 7091 } else { 7092 if (!A->ops->ishermitian) { 7093 const MatType mattype; 7094 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7095 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for hermitian",mattype); 7096 } 7097 ierr = (*A->ops->ishermitian)(A,tol,flg);CHKERRQ(ierr); 7098 } 7099 PetscFunctionReturn(0); 7100 } 7101 7102 #undef __FUNCT__ 7103 #define __FUNCT__ "MatIsSymmetricKnown" 7104 /*@ 7105 MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric. 7106 7107 Collective on Mat 7108 7109 Input Parameter: 7110 . A - the matrix to check 7111 7112 Output Parameters: 7113 + set - if the symmetric flag is set (this tells you if the next flag is valid) 7114 - flg - the result 7115 7116 Level: advanced 7117 7118 Concepts: matrix^symmetry 7119 7120 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric() 7121 if you want it explicitly checked 7122 7123 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 7124 @*/ 7125 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg) 7126 { 7127 PetscFunctionBegin; 7128 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7129 PetscValidPointer(set,2); 7130 PetscValidPointer(flg,3); 7131 if (A->symmetric_set) { 7132 *set = PETSC_TRUE; 7133 *flg = A->symmetric; 7134 } else { 7135 *set = PETSC_FALSE; 7136 } 7137 PetscFunctionReturn(0); 7138 } 7139 7140 #undef __FUNCT__ 7141 #define __FUNCT__ "MatIsHermitianKnown" 7142 /*@ 7143 MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian. 7144 7145 Collective on Mat 7146 7147 Input Parameter: 7148 . A - the matrix to check 7149 7150 Output Parameters: 7151 + set - if the hermitian flag is set (this tells you if the next flag is valid) 7152 - flg - the result 7153 7154 Level: advanced 7155 7156 Concepts: matrix^symmetry 7157 7158 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian() 7159 if you want it explicitly checked 7160 7161 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 7162 @*/ 7163 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg) 7164 { 7165 PetscFunctionBegin; 7166 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7167 PetscValidPointer(set,2); 7168 PetscValidPointer(flg,3); 7169 if (A->hermitian_set) { 7170 *set = PETSC_TRUE; 7171 *flg = A->hermitian; 7172 } else { 7173 *set = PETSC_FALSE; 7174 } 7175 PetscFunctionReturn(0); 7176 } 7177 7178 #undef __FUNCT__ 7179 #define __FUNCT__ "MatIsStructurallySymmetric" 7180 /*@ 7181 MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric 7182 7183 Collective on Mat 7184 7185 Input Parameter: 7186 . A - the matrix to test 7187 7188 Output Parameters: 7189 . flg - the result 7190 7191 Level: intermediate 7192 7193 Concepts: matrix^symmetry 7194 7195 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption() 7196 @*/ 7197 PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg) 7198 { 7199 PetscErrorCode ierr; 7200 7201 PetscFunctionBegin; 7202 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7203 PetscValidPointer(flg,2); 7204 if (!A->structurally_symmetric_set) { 7205 if (!A->ops->isstructurallysymmetric) SETERRQ(PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric"); 7206 ierr = (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);CHKERRQ(ierr); 7207 A->structurally_symmetric_set = PETSC_TRUE; 7208 } 7209 *flg = A->structurally_symmetric; 7210 PetscFunctionReturn(0); 7211 } 7212 7213 #undef __FUNCT__ 7214 #define __FUNCT__ "MatStashGetInfo" 7215 extern PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*); 7216 /*@ 7217 MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need 7218 to be communicated to other processors during the MatAssemblyBegin/End() process 7219 7220 Not collective 7221 7222 Input Parameter: 7223 . vec - the vector 7224 7225 Output Parameters: 7226 + nstash - the size of the stash 7227 . reallocs - the number of additional mallocs incurred. 7228 . bnstash - the size of the block stash 7229 - breallocs - the number of additional mallocs incurred.in the block stash 7230 7231 Level: advanced 7232 7233 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize() 7234 7235 @*/ 7236 PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs) 7237 { 7238 PetscErrorCode ierr; 7239 PetscFunctionBegin; 7240 ierr = MatStashGetInfo_Private(&mat->stash,nstash,reallocs);CHKERRQ(ierr); 7241 ierr = MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);CHKERRQ(ierr); 7242 PetscFunctionReturn(0); 7243 } 7244 7245 #undef __FUNCT__ 7246 #define __FUNCT__ "MatGetVecs" 7247 /*@C 7248 MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 7249 parallel layout 7250 7251 Collective on Mat 7252 7253 Input Parameter: 7254 . mat - the matrix 7255 7256 Output Parameter: 7257 + right - (optional) vector that the matrix can be multiplied against 7258 - left - (optional) vector that the matrix vector product can be stored in 7259 7260 Level: advanced 7261 7262 .seealso: MatCreate() 7263 @*/ 7264 PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left) 7265 { 7266 PetscErrorCode ierr; 7267 7268 PetscFunctionBegin; 7269 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7270 PetscValidType(mat,1); 7271 ierr = MatPreallocated(mat);CHKERRQ(ierr); 7272 if (mat->ops->getvecs) { 7273 ierr = (*mat->ops->getvecs)(mat,right,left);CHKERRQ(ierr); 7274 } else { 7275 PetscMPIInt size; 7276 ierr = MPI_Comm_size(((PetscObject)mat)->comm, &size);CHKERRQ(ierr); 7277 if (right) { 7278 ierr = VecCreate(((PetscObject)mat)->comm,right);CHKERRQ(ierr); 7279 ierr = VecSetSizes(*right,mat->cmap->n,PETSC_DETERMINE);CHKERRQ(ierr); 7280 ierr = VecSetBlockSize(*right,mat->rmap->bs);CHKERRQ(ierr); 7281 if (size > 1) { 7282 /* New vectors uses Mat cmap and does not create a new one */ 7283 ierr = PetscLayoutDestroy((*right)->map);CHKERRQ(ierr); 7284 (*right)->map = mat->cmap; 7285 mat->cmap->refcnt++; 7286 7287 ierr = VecSetType(*right,VECMPI);CHKERRQ(ierr); 7288 } else {ierr = VecSetType(*right,VECSEQ);CHKERRQ(ierr);} 7289 } 7290 if (left) { 7291 ierr = VecCreate(((PetscObject)mat)->comm,left);CHKERRQ(ierr); 7292 ierr = VecSetSizes(*left,mat->rmap->n,PETSC_DETERMINE);CHKERRQ(ierr); 7293 ierr = VecSetBlockSize(*left,mat->rmap->bs);CHKERRQ(ierr); 7294 if (size > 1) { 7295 /* New vectors uses Mat rmap and does not create a new one */ 7296 ierr = PetscLayoutDestroy((*left)->map);CHKERRQ(ierr); 7297 (*left)->map = mat->rmap; 7298 mat->rmap->refcnt++; 7299 7300 ierr = VecSetType(*left,VECMPI);CHKERRQ(ierr); 7301 } else {ierr = VecSetType(*left,VECSEQ);CHKERRQ(ierr);} 7302 } 7303 } 7304 if (mat->mapping) { 7305 if (right) {ierr = VecSetLocalToGlobalMapping(*right,mat->mapping);CHKERRQ(ierr);} 7306 if (left) {ierr = VecSetLocalToGlobalMapping(*left,mat->mapping);CHKERRQ(ierr);} 7307 } 7308 if (mat->bmapping) { 7309 if (right) {ierr = VecSetLocalToGlobalMappingBlock(*right,mat->bmapping);CHKERRQ(ierr);} 7310 if (left) {ierr = VecSetLocalToGlobalMappingBlock(*left,mat->bmapping);CHKERRQ(ierr);} 7311 } 7312 PetscFunctionReturn(0); 7313 } 7314 7315 #undef __FUNCT__ 7316 #define __FUNCT__ "MatFactorInfoInitialize" 7317 /*@C 7318 MatFactorInfoInitialize - Initializes a MatFactorInfo data structure 7319 with default values. 7320 7321 Not Collective 7322 7323 Input Parameters: 7324 . info - the MatFactorInfo data structure 7325 7326 7327 Notes: The solvers are generally used through the KSP and PC objects, for example 7328 PCLU, PCILU, PCCHOLESKY, PCICC 7329 7330 Level: developer 7331 7332 .seealso: MatFactorInfo 7333 7334 Developer Note: fortran interface is not autogenerated as the f90 7335 interface defintion cannot be generated correctly [due to MatFactorInfo] 7336 7337 @*/ 7338 7339 PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info) 7340 { 7341 PetscErrorCode ierr; 7342 7343 PetscFunctionBegin; 7344 ierr = PetscMemzero(info,sizeof(MatFactorInfo));CHKERRQ(ierr); 7345 PetscFunctionReturn(0); 7346 } 7347 7348 #undef __FUNCT__ 7349 #define __FUNCT__ "MatPtAP" 7350 /*@ 7351 MatPtAP - Creates the matrix projection C = P^T * A * P 7352 7353 Collective on Mat 7354 7355 Input Parameters: 7356 + A - the matrix 7357 . P - the projection matrix 7358 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7359 - fill - expected fill as ratio of nnz(C)/nnz(A) 7360 7361 Output Parameters: 7362 . C - the product matrix 7363 7364 Notes: 7365 C will be created and must be destroyed by the user with MatDestroy(). 7366 7367 This routine is currently only implemented for pairs of AIJ matrices and classes 7368 which inherit from AIJ. 7369 7370 Level: intermediate 7371 7372 .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult() 7373 @*/ 7374 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C) 7375 { 7376 PetscErrorCode ierr; 7377 7378 PetscFunctionBegin; 7379 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7380 PetscValidType(A,1); 7381 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7382 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7383 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7384 PetscValidType(P,2); 7385 ierr = MatPreallocated(P);CHKERRQ(ierr); 7386 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7387 if (P->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7388 PetscValidPointer(C,3); 7389 if (P->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap->N,A->cmap->N); 7390 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7391 ierr = MatPreallocated(A);CHKERRQ(ierr); 7392 7393 if (!A->ops->ptap) { 7394 const MatType mattype; 7395 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7396 SETERRQ1(PETSC_ERR_SUP,"Matrix of type <%s> does not support PtAP",mattype); 7397 } 7398 ierr = PetscLogEventBegin(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 7399 ierr = (*A->ops->ptap)(A,P,scall,fill,C);CHKERRQ(ierr); 7400 ierr = PetscLogEventEnd(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 7401 7402 PetscFunctionReturn(0); 7403 } 7404 7405 #undef __FUNCT__ 7406 #define __FUNCT__ "MatPtAPNumeric" 7407 /*@ 7408 MatPtAPNumeric - Computes the matrix projection C = P^T * A * P 7409 7410 Collective on Mat 7411 7412 Input Parameters: 7413 + A - the matrix 7414 - P - the projection matrix 7415 7416 Output Parameters: 7417 . C - the product matrix 7418 7419 Notes: 7420 C must have been created by calling MatPtAPSymbolic and must be destroyed by 7421 the user using MatDeatroy(). 7422 7423 This routine is currently only implemented for pairs of AIJ matrices and classes 7424 which inherit from AIJ. C will be of type MATAIJ. 7425 7426 Level: intermediate 7427 7428 .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric() 7429 @*/ 7430 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C) 7431 { 7432 PetscErrorCode ierr; 7433 7434 PetscFunctionBegin; 7435 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7436 PetscValidType(A,1); 7437 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7438 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7439 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7440 PetscValidType(P,2); 7441 ierr = MatPreallocated(P);CHKERRQ(ierr); 7442 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7443 if (P->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7444 PetscValidHeaderSpecific(C,MAT_CLASSID,3); 7445 PetscValidType(C,3); 7446 ierr = MatPreallocated(C);CHKERRQ(ierr); 7447 if (C->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7448 if (P->cmap->N!=C->rmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap->N,C->rmap->N); 7449 if (P->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap->N,A->cmap->N); 7450 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); 7451 if (P->cmap->N!=C->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->cmap->N,C->cmap->N); 7452 ierr = MatPreallocated(A);CHKERRQ(ierr); 7453 7454 ierr = PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 7455 ierr = (*A->ops->ptapnumeric)(A,P,C);CHKERRQ(ierr); 7456 ierr = PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 7457 PetscFunctionReturn(0); 7458 } 7459 7460 #undef __FUNCT__ 7461 #define __FUNCT__ "MatPtAPSymbolic" 7462 /*@ 7463 MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P 7464 7465 Collective on Mat 7466 7467 Input Parameters: 7468 + A - the matrix 7469 - P - the projection matrix 7470 7471 Output Parameters: 7472 . C - the (i,j) structure of the product matrix 7473 7474 Notes: 7475 C will be created and must be destroyed by the user with MatDestroy(). 7476 7477 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 7478 which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using 7479 this (i,j) structure by calling MatPtAPNumeric(). 7480 7481 Level: intermediate 7482 7483 .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic() 7484 @*/ 7485 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C) 7486 { 7487 PetscErrorCode ierr; 7488 7489 PetscFunctionBegin; 7490 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7491 PetscValidType(A,1); 7492 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7493 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7494 if (fill <1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7495 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7496 PetscValidType(P,2); 7497 ierr = MatPreallocated(P);CHKERRQ(ierr); 7498 if (!P->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7499 if (P->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7500 PetscValidPointer(C,3); 7501 7502 if (P->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",P->rmap->N,A->cmap->N); 7503 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); 7504 ierr = MatPreallocated(A);CHKERRQ(ierr); 7505 ierr = PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 7506 ierr = (*A->ops->ptapsymbolic)(A,P,fill,C);CHKERRQ(ierr); 7507 ierr = PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 7508 7509 ierr = MatSetBlockSize(*C,A->rmap->bs);CHKERRQ(ierr); 7510 7511 PetscFunctionReturn(0); 7512 } 7513 7514 #undef __FUNCT__ 7515 #define __FUNCT__ "MatMatMult" 7516 /*@ 7517 MatMatMult - Performs Matrix-Matrix Multiplication C=A*B. 7518 7519 Collective on Mat 7520 7521 Input Parameters: 7522 + A - the left matrix 7523 . B - the right matrix 7524 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7525 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if you do not have a good estimate 7526 if the result is a dense matrix this is irrelevent 7527 7528 Output Parameters: 7529 . C - the product matrix 7530 7531 Notes: 7532 Unless scall is MAT_REUSE_MATRIX C will be created. 7533 7534 MAT_REUSE_MATRIX can only be used if the matrices A and B have the same nonzero pattern as in the previous call 7535 7536 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7537 actually needed. 7538 7539 If you have many matrices with the same non-zero structure to multiply, you 7540 should either 7541 $ 1) use MAT_REUSE_MATRIX in all calls but the first or 7542 $ 2) call MatMatMultSymbolic() once and then MatMatMultNumeric() for each product needed 7543 7544 Level: intermediate 7545 7546 .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP() 7547 @*/ 7548 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 7549 { 7550 PetscErrorCode ierr; 7551 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 7552 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 7553 PetscErrorCode (*mult)(Mat,Mat,MatReuse,PetscReal,Mat *)=PETSC_NULL; 7554 7555 PetscFunctionBegin; 7556 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7557 PetscValidType(A,1); 7558 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7559 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7560 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7561 PetscValidType(B,2); 7562 ierr = MatPreallocated(B);CHKERRQ(ierr); 7563 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7564 if (B->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7565 PetscValidPointer(C,3); 7566 if (B->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap->N,A->cmap->N); 7567 if (scall == MAT_REUSE_MATRIX){ 7568 PetscValidPointer(*C,5); 7569 PetscValidHeaderSpecific(*C,MAT_CLASSID,5); 7570 } 7571 if (fill == PETSC_DEFAULT || fill == PETSC_DECIDE) fill = 2.0; 7572 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7573 ierr = MatPreallocated(A);CHKERRQ(ierr); 7574 7575 fA = A->ops->matmult; 7576 fB = B->ops->matmult; 7577 if (fB == fA) { 7578 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",((PetscObject)B)->type_name); 7579 mult = fB; 7580 } else { 7581 /* dispatch based on the type of A and B */ 7582 char multname[256]; 7583 ierr = PetscStrcpy(multname,"MatMatMult_");CHKERRQ(ierr); 7584 ierr = PetscStrcat(multname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7585 ierr = PetscStrcat(multname,"_");CHKERRQ(ierr); 7586 ierr = PetscStrcat(multname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7587 ierr = PetscStrcat(multname,"_C");CHKERRQ(ierr); /* e.g., multname = "MatMatMult_seqdense_seqaij_C" */ 7588 ierr = PetscObjectQueryFunction((PetscObject)B,multname,(void (**)(void))&mult);CHKERRQ(ierr); 7589 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); 7590 } 7591 ierr = PetscLogEventBegin(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 7592 ierr = (*mult)(A,B,scall,fill,C);CHKERRQ(ierr); 7593 ierr = PetscLogEventEnd(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 7594 PetscFunctionReturn(0); 7595 } 7596 7597 #undef __FUNCT__ 7598 #define __FUNCT__ "MatMatMultSymbolic" 7599 /*@ 7600 MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure 7601 of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric(). 7602 7603 Collective on Mat 7604 7605 Input Parameters: 7606 + A - the left matrix 7607 . B - the right matrix 7608 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if you do not have a good estimate, 7609 if C is a dense matrix this is irrelevent 7610 7611 Output Parameters: 7612 . C - the product matrix 7613 7614 Notes: 7615 Unless scall is MAT_REUSE_MATRIX C will be created. 7616 7617 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7618 actually needed. 7619 7620 This routine is currently implemented for 7621 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type AIJ 7622 - pairs of AIJ (A) and Dense (B) matrix, C will be of type Dense. 7623 - pairs of Dense (A) and AIJ (B) matrix, C will be of type Dense. 7624 7625 Level: intermediate 7626 7627 .seealso: MatMatMult(), MatMatMultNumeric() 7628 @*/ 7629 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C) 7630 { 7631 PetscErrorCode ierr; 7632 PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *); 7633 PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *); 7634 PetscErrorCode (*symbolic)(Mat,Mat,PetscReal,Mat *)=PETSC_NULL; 7635 7636 PetscFunctionBegin; 7637 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7638 PetscValidType(A,1); 7639 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7640 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7641 7642 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7643 PetscValidType(B,2); 7644 ierr = MatPreallocated(B);CHKERRQ(ierr); 7645 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7646 if (B->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7647 PetscValidPointer(C,3); 7648 7649 if (B->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap->N,A->cmap->N); 7650 if (fill == PETSC_DEFAULT) fill = 2.0; 7651 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 7652 ierr = MatPreallocated(A);CHKERRQ(ierr); 7653 7654 Asymbolic = A->ops->matmultsymbolic; 7655 Bsymbolic = B->ops->matmultsymbolic; 7656 if (Asymbolic == Bsymbolic){ 7657 if (!Bsymbolic) SETERRQ1(PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",((PetscObject)B)->type_name); 7658 symbolic = Bsymbolic; 7659 } else { /* dispatch based on the type of A and B */ 7660 char symbolicname[256]; 7661 ierr = PetscStrcpy(symbolicname,"MatMatMultSymbolic_");CHKERRQ(ierr); 7662 ierr = PetscStrcat(symbolicname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7663 ierr = PetscStrcat(symbolicname,"_");CHKERRQ(ierr); 7664 ierr = PetscStrcat(symbolicname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7665 ierr = PetscStrcat(symbolicname,"_C");CHKERRQ(ierr); 7666 ierr = PetscObjectQueryFunction((PetscObject)B,symbolicname,(void (**)(void))&symbolic);CHKERRQ(ierr); 7667 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); 7668 } 7669 ierr = PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 7670 ierr = (*symbolic)(A,B,fill,C);CHKERRQ(ierr); 7671 ierr = PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 7672 PetscFunctionReturn(0); 7673 } 7674 7675 #undef __FUNCT__ 7676 #define __FUNCT__ "MatMatMultNumeric" 7677 /*@ 7678 MatMatMultNumeric - Performs the numeric matrix-matrix product. 7679 Call this routine after first calling MatMatMultSymbolic(). 7680 7681 Collective on Mat 7682 7683 Input Parameters: 7684 + A - the left matrix 7685 - B - the right matrix 7686 7687 Output Parameters: 7688 . C - the product matrix, which was created by from MatMatMultSymbolic() or a call to MatMatMult(). 7689 7690 Notes: 7691 C must have been created with MatMatMultSymbolic(). 7692 7693 This routine is currently implemented for 7694 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ. 7695 - pairs of AIJ (A) and Dense (B) matrix, C will be of type Dense. 7696 - pairs of Dense (A) and AIJ (B) matrix, C will be of type Dense. 7697 7698 Level: intermediate 7699 7700 .seealso: MatMatMult(), MatMatMultSymbolic() 7701 @*/ 7702 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C) 7703 { 7704 PetscErrorCode ierr; 7705 PetscErrorCode (*Anumeric)(Mat,Mat,Mat); 7706 PetscErrorCode (*Bnumeric)(Mat,Mat,Mat); 7707 PetscErrorCode (*numeric)(Mat,Mat,Mat)=PETSC_NULL; 7708 7709 PetscFunctionBegin; 7710 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7711 PetscValidType(A,1); 7712 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7713 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7714 7715 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7716 PetscValidType(B,2); 7717 ierr = MatPreallocated(B);CHKERRQ(ierr); 7718 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7719 if (B->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7720 7721 PetscValidHeaderSpecific(C,MAT_CLASSID,3); 7722 PetscValidType(C,3); 7723 ierr = MatPreallocated(C);CHKERRQ(ierr); 7724 if (!C->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7725 if (C->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7726 7727 if (B->cmap->N!=C->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->cmap->N,C->cmap->N); 7728 if (B->rmap->N!=A->cmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap->N,A->cmap->N); 7729 if (A->rmap->N!=C->rmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",A->rmap->N,C->rmap->N); 7730 ierr = MatPreallocated(A);CHKERRQ(ierr); 7731 7732 Anumeric = A->ops->matmultnumeric; 7733 Bnumeric = B->ops->matmultnumeric; 7734 if (Anumeric == Bnumeric){ 7735 if (!Bnumeric) SETERRQ1(PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",((PetscObject)B)->type_name); 7736 numeric = Bnumeric; 7737 } else { 7738 char numericname[256]; 7739 ierr = PetscStrcpy(numericname,"MatMatMultNumeric_");CHKERRQ(ierr); 7740 ierr = PetscStrcat(numericname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7741 ierr = PetscStrcat(numericname,"_");CHKERRQ(ierr); 7742 ierr = PetscStrcat(numericname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7743 ierr = PetscStrcat(numericname,"_C");CHKERRQ(ierr); 7744 ierr = PetscObjectQueryFunction((PetscObject)B,numericname,(void (**)(void))&numeric);CHKERRQ(ierr); 7745 if (!numeric) 7746 SETERRQ2(PETSC_ERR_ARG_INCOMP,"MatMatMultNumeric requires A, %s, to be compatible with B, %s",((PetscObject)A)->type_name,((PetscObject)B)->type_name); 7747 } 7748 ierr = PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 7749 ierr = (*numeric)(A,B,C);CHKERRQ(ierr); 7750 ierr = PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 7751 PetscFunctionReturn(0); 7752 } 7753 7754 #undef __FUNCT__ 7755 #define __FUNCT__ "MatMatMultTranspose" 7756 /*@ 7757 MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B. 7758 7759 Collective on Mat 7760 7761 Input Parameters: 7762 + A - the left matrix 7763 . B - the right matrix 7764 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7765 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if not known 7766 7767 Output Parameters: 7768 . C - the product matrix 7769 7770 Notes: 7771 C will be created if MAT_INITIAL_MATRIX and must be destroyed by the user with MatDestroy(). 7772 7773 MAT_REUSE_MATRIX can only be used if the matrices A and B have the same nonzero pattern as in the previous call 7774 7775 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7776 actually needed. 7777 7778 This routine is currently only implemented for pairs of SeqAIJ matrices and pairs of SeqDense matrices and classes 7779 which inherit from SeqAIJ. C will be of type MATSEQAIJ. 7780 7781 Level: intermediate 7782 7783 .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP() 7784 @*/ 7785 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 7786 { 7787 PetscErrorCode ierr; 7788 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 7789 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 7790 7791 PetscFunctionBegin; 7792 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7793 PetscValidType(A,1); 7794 if (!A->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7795 if (A->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7796 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7797 PetscValidType(B,2); 7798 ierr = MatPreallocated(B);CHKERRQ(ierr); 7799 if (!B->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7800 if (B->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7801 PetscValidPointer(C,3); 7802 if (B->rmap->N!=A->rmap->N) SETERRQ2(PETSC_ERR_ARG_SIZ,"Matrix dimensions are incompatible, %D != %D",B->rmap->N,A->rmap->N); 7803 if (fill == PETSC_DEFAULT || fill == PETSC_DECIDE) fill = 2.0; 7804 if (fill < 1.0) SETERRQ1(PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 7805 ierr = MatPreallocated(A);CHKERRQ(ierr); 7806 7807 fA = A->ops->matmulttranspose; 7808 if (!fA) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",((PetscObject)A)->type_name); 7809 fB = B->ops->matmulttranspose; 7810 if (!fB) SETERRQ1(PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",((PetscObject)B)->type_name); 7811 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); 7812 7813 ierr = PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 7814 ierr = (*A->ops->matmulttranspose)(A,B,scall,fill,C);CHKERRQ(ierr); 7815 ierr = PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 7816 7817 PetscFunctionReturn(0); 7818 } 7819 7820 #undef __FUNCT__ 7821 #define __FUNCT__ "MatGetRedundantMatrix" 7822 /*@C 7823 MatGetRedundantMatrix - Create redundant matrices and put them into processors of subcommunicators. 7824 7825 Collective on Mat 7826 7827 Input Parameters: 7828 + mat - the matrix 7829 . nsubcomm - the number of subcommunicators (= number of redundant pareallel or sequential matrices) 7830 . subcomm - MPI communicator split from the communicator where mat resides in 7831 . mlocal_red - number of local rows of the redundant matrix 7832 - reuse - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7833 7834 Output Parameter: 7835 . matredundant - redundant matrix 7836 7837 Notes: 7838 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 7839 original matrix has not changed from that last call to MatGetRedundantMatrix(). 7840 7841 This routine creates the duplicated matrices in subcommunicators; you should NOT create them before 7842 calling it. 7843 7844 Only MPIAIJ matrix is supported. 7845 7846 Level: advanced 7847 7848 Concepts: subcommunicator 7849 Concepts: duplicate matrix 7850 7851 .seealso: MatDestroy() 7852 @*/ 7853 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRedundantMatrix(Mat mat,PetscInt nsubcomm,MPI_Comm subcomm,PetscInt mlocal_red,MatReuse reuse,Mat *matredundant) 7854 { 7855 PetscErrorCode ierr; 7856 7857 PetscFunctionBegin; 7858 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7859 if (nsubcomm && reuse == MAT_REUSE_MATRIX) { 7860 PetscValidPointer(*matredundant,6); 7861 PetscValidHeaderSpecific(*matredundant,MAT_CLASSID,6); 7862 } 7863 if (!mat->ops->getredundantmatrix) SETERRQ1(PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 7864 if (!mat->assembled) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7865 if (mat->factortype) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7866 ierr = MatPreallocated(mat);CHKERRQ(ierr); 7867 7868 ierr = PetscLogEventBegin(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 7869 ierr = (*mat->ops->getredundantmatrix)(mat,nsubcomm,subcomm,mlocal_red,reuse,matredundant);CHKERRQ(ierr); 7870 ierr = PetscLogEventEnd(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 7871 PetscFunctionReturn(0); 7872 } 7873