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