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