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