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