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