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