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