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