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