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