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