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