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