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