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