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