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