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_SYMMETRIC - symmetric in terms of both structure and value 4920 . MAT_HERMITIAN - transpose is the complex conjugation 4921 . MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure 4922 - MAT_SYMMETRY_ETERNAL - if you would like the symmetry/Hermitian flag 4923 you set to be kept with all future use of the matrix 4924 including after MatAssemblyBegin/End() which could 4925 potentially change the symmetry structure, i.e. you 4926 KNOW the matrix will ALWAYS have the property you set. 4927 4928 4929 Options For Use with MatSetValues(): 4930 Insert a logically dense subblock, which can be 4931 . MAT_ROW_ORIENTED - row-oriented (default) 4932 4933 Note these options reflect the data you pass in with MatSetValues(); it has 4934 nothing to do with how the data is stored internally in the matrix 4935 data structure. 4936 4937 When (re)assembling a matrix, we can restrict the input for 4938 efficiency/debugging purposes. These options include 4939 + MAT_NEW_NONZERO_LOCATIONS - additional insertions will be 4940 allowed if they generate a new nonzero 4941 . MAT_NEW_DIAGONALS - new diagonals will be allowed (for block diagonal format only) 4942 . MAT_IGNORE_OFF_PROC_ENTRIES - drops off-processor entries 4943 . MAT_NEW_NONZERO_LOCATION_ERR - generates an error for new matrix entry 4944 - MAT_USE_HASH_TABLE - uses a hash table to speed up matrix assembly 4945 4946 Notes: 4947 Some options are relevant only for particular matrix types and 4948 are thus ignored by others. Other options are not supported by 4949 certain matrix types and will generate an error message if set. 4950 4951 If using a Fortran 77 module to compute a matrix, one may need to 4952 use the column-oriented option (or convert to the row-oriented 4953 format). 4954 4955 MAT_NEW_NONZERO_LOCATIONS set to PETSC_FALSE indicates that any add or insertion 4956 that would generate a new entry in the nonzero structure is instead 4957 ignored. Thus, if memory has not alredy been allocated for this particular 4958 data, then the insertion is ignored. For dense matrices, in which 4959 the entire array is allocated, no entries are ever ignored. 4960 Set after the first MatAssemblyEnd() 4961 4962 MAT_NEW_NONZERO_LOCATION_ERR indicates that any add or insertion 4963 that would generate a new entry in the nonzero structure instead produces 4964 an error. (Currently supported for AIJ and BAIJ formats only.) 4965 This is a useful flag when using SAME_NONZERO_PATTERN in calling 4966 KSPSetOperators() to ensure that the nonzero pattern truely does 4967 remain unchanged. Set after the first MatAssemblyEnd() 4968 4969 MAT_NEW_NONZERO_ALLOCATION_ERR indicates that any add or insertion 4970 that would generate a new entry that has not been preallocated will 4971 instead produce an error. (Currently supported for AIJ and BAIJ formats 4972 only.) This is a useful flag when debugging matrix memory preallocation. 4973 4974 MAT_IGNORE_OFF_PROC_ENTRIES indicates entries destined for 4975 other processors should be dropped, rather than stashed. 4976 This is useful if you know that the "owning" processor is also 4977 always generating the correct matrix entries, so that PETSc need 4978 not transfer duplicate entries generated on another processor. 4979 4980 MAT_USE_HASH_TABLE indicates that a hash table be used to improve the 4981 searches during matrix assembly. When this flag is set, the hash table 4982 is created during the first Matrix Assembly. This hash table is 4983 used the next time through, during MatSetVaules()/MatSetVaulesBlocked() 4984 to improve the searching of indices. MAT_NEW_NONZERO_LOCATIONS flag 4985 should be used with MAT_USE_HASH_TABLE flag. This option is currently 4986 supported by MATMPIBAIJ format only. 4987 4988 MAT_KEEP_NONZERO_PATTERN indicates when MatZeroRows() is called the zeroed entries 4989 are kept in the nonzero structure 4990 4991 MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating 4992 a zero location in the matrix 4993 4994 MAT_USE_INODES - indicates using inode version of the code - works with AIJ and 4995 ROWBS matrix types 4996 4997 Level: intermediate 4998 4999 Concepts: matrices^setting options 5000 5001 @*/ 5002 PetscErrorCode PETSCMAT_DLLEXPORT MatSetOption(Mat mat,MatOption op,PetscTruth flg) 5003 { 5004 PetscErrorCode ierr; 5005 5006 PetscFunctionBegin; 5007 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5008 PetscValidType(mat,1); 5009 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); 5010 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()"); 5011 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5012 switch (op) { 5013 case MAT_SYMMETRIC: 5014 mat->symmetric = flg; 5015 if (flg) mat->structurally_symmetric = PETSC_TRUE; 5016 mat->symmetric_set = PETSC_TRUE; 5017 mat->structurally_symmetric_set = flg; 5018 break; 5019 case MAT_HERMITIAN: 5020 mat->hermitian = flg; 5021 if (flg) mat->structurally_symmetric = PETSC_TRUE; 5022 mat->hermitian_set = PETSC_TRUE; 5023 mat->structurally_symmetric_set = flg; 5024 break; 5025 case MAT_STRUCTURALLY_SYMMETRIC: 5026 mat->structurally_symmetric = flg; 5027 mat->structurally_symmetric_set = PETSC_TRUE; 5028 break; 5029 case MAT_SYMMETRY_ETERNAL: 5030 mat->symmetric_eternal = flg; 5031 break; 5032 default: 5033 break; 5034 } 5035 if (mat->ops->setoption) { 5036 ierr = (*mat->ops->setoption)(mat,op,flg);CHKERRQ(ierr); 5037 } 5038 PetscFunctionReturn(0); 5039 } 5040 5041 #undef __FUNCT__ 5042 #define __FUNCT__ "MatZeroEntries" 5043 /*@ 5044 MatZeroEntries - Zeros all entries of a matrix. For sparse matrices 5045 this routine retains the old nonzero structure. 5046 5047 Collective on Mat 5048 5049 Input Parameters: 5050 . mat - the matrix 5051 5052 Level: intermediate 5053 5054 Concepts: matrices^zeroing 5055 5056 .seealso: MatZeroRows() 5057 @*/ 5058 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroEntries(Mat mat) 5059 { 5060 PetscErrorCode ierr; 5061 5062 PetscFunctionBegin; 5063 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5064 PetscValidType(mat,1); 5065 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5066 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"); 5067 if (!mat->ops->zeroentries) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5068 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5069 5070 ierr = PetscLogEventBegin(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 5071 ierr = (*mat->ops->zeroentries)(mat);CHKERRQ(ierr); 5072 ierr = PetscLogEventEnd(MAT_ZeroEntries,mat,0,0,0);CHKERRQ(ierr); 5073 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5074 PetscFunctionReturn(0); 5075 } 5076 5077 #undef __FUNCT__ 5078 #define __FUNCT__ "MatZeroRows" 5079 /*@C 5080 MatZeroRows - Zeros all entries (except possibly the main diagonal) 5081 of a set of rows of a matrix. 5082 5083 Collective on Mat 5084 5085 Input Parameters: 5086 + mat - the matrix 5087 . numRows - the number of rows to remove 5088 . rows - the global row indices 5089 - diag - value put in all diagonals of eliminated rows (0.0 will even eliminate diagonal entry) 5090 5091 Notes: 5092 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 5093 but does not release memory. For the dense and block diagonal 5094 formats this does not alter the nonzero structure. 5095 5096 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5097 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5098 merely zeroed. 5099 5100 The user can set a value in the diagonal entry (or for the AIJ and 5101 row formats can optionally remove the main diagonal entry from the 5102 nonzero structure as well, by passing 0.0 as the final argument). 5103 5104 For the parallel case, all processes that share the matrix (i.e., 5105 those in the communicator used for matrix creation) MUST call this 5106 routine, regardless of whether any rows being zeroed are owned by 5107 them. 5108 5109 Each processor can indicate any rows in the entire matrix to be zeroed (i.e. each process does NOT have to 5110 list only rows local to itself). 5111 5112 Level: intermediate 5113 5114 Concepts: matrices^zeroing rows 5115 5116 .seealso: MatZeroRowsIS(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 5117 @*/ 5118 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRows(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 5119 { 5120 PetscErrorCode ierr; 5121 5122 PetscFunctionBegin; 5123 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5124 PetscValidType(mat,1); 5125 if (numRows) PetscValidIntPointer(rows,3); 5126 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5127 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5128 if (!mat->ops->zerorows) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5129 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5130 5131 ierr = (*mat->ops->zerorows)(mat,numRows,rows,diag);CHKERRQ(ierr); 5132 ierr = MatView_Private(mat);CHKERRQ(ierr); 5133 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5134 PetscFunctionReturn(0); 5135 } 5136 5137 #undef __FUNCT__ 5138 #define __FUNCT__ "MatZeroRowsIS" 5139 /*@C 5140 MatZeroRowsIS - Zeros all entries (except possibly the main diagonal) 5141 of a set of rows of a matrix. 5142 5143 Collective on Mat 5144 5145 Input Parameters: 5146 + mat - the matrix 5147 . is - index set of rows to remove 5148 - diag - value put in all diagonals of eliminated rows 5149 5150 Notes: 5151 For the AIJ and BAIJ matrix formats this removes the old nonzero structure, 5152 but does not release memory. For the dense and block diagonal 5153 formats this does not alter the nonzero structure. 5154 5155 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5156 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5157 merely zeroed. 5158 5159 The user can set a value in the diagonal entry (or for the AIJ and 5160 row formats can optionally remove the main diagonal entry from the 5161 nonzero structure as well, by passing 0.0 as the final argument). 5162 5163 For the parallel case, all processes that share the matrix (i.e., 5164 those in the communicator used for matrix creation) MUST call this 5165 routine, regardless of whether any rows being zeroed are owned by 5166 them. 5167 5168 Each processor should list the rows that IT wants zeroed 5169 5170 Level: intermediate 5171 5172 Concepts: matrices^zeroing rows 5173 5174 .seealso: MatZeroRows(), MatZeroEntries(), MatZeroRowsLocal(), MatSetOption() 5175 @*/ 5176 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsIS(Mat mat,IS is,PetscScalar diag) 5177 { 5178 PetscInt numRows; 5179 const PetscInt *rows; 5180 PetscErrorCode ierr; 5181 5182 PetscFunctionBegin; 5183 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5184 PetscValidType(mat,1); 5185 PetscValidHeaderSpecific(is,IS_CLASSID,2); 5186 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 5187 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 5188 ierr = MatZeroRows(mat,numRows,rows,diag);CHKERRQ(ierr); 5189 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 5190 PetscFunctionReturn(0); 5191 } 5192 5193 #undef __FUNCT__ 5194 #define __FUNCT__ "MatZeroRowsLocal" 5195 /*@C 5196 MatZeroRowsLocal - Zeros all entries (except possibly the main diagonal) 5197 of a set of rows of a matrix; using local numbering of rows. 5198 5199 Collective on Mat 5200 5201 Input Parameters: 5202 + mat - the matrix 5203 . numRows - the number of rows to remove 5204 . rows - the global row indices 5205 - diag - value put in all diagonals of eliminated rows 5206 5207 Notes: 5208 Before calling MatZeroRowsLocal(), the user must first set the 5209 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 5210 5211 For the AIJ matrix formats this removes the old nonzero structure, 5212 but does not release memory. For the dense and block diagonal 5213 formats this does not alter the nonzero structure. 5214 5215 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5216 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5217 merely zeroed. 5218 5219 The user can set a value in the diagonal entry (or for the AIJ and 5220 row formats can optionally remove the main diagonal entry from the 5221 nonzero structure as well, by passing 0.0 as the final argument). 5222 5223 Level: intermediate 5224 5225 Concepts: matrices^zeroing 5226 5227 .seealso: MatZeroRows(), MatZeroRowsLocalIS(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 5228 @*/ 5229 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocal(Mat mat,PetscInt numRows,const PetscInt rows[],PetscScalar diag) 5230 { 5231 PetscErrorCode ierr; 5232 5233 PetscFunctionBegin; 5234 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5235 PetscValidType(mat,1); 5236 if (numRows) PetscValidIntPointer(rows,3); 5237 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5238 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5239 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5240 5241 if (mat->ops->zerorowslocal) { 5242 ierr = (*mat->ops->zerorowslocal)(mat,numRows,rows,diag);CHKERRQ(ierr); 5243 } else { 5244 IS is, newis; 5245 const PetscInt *newRows; 5246 5247 if (!mat->mapping) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Need to provide local to global mapping to matrix first"); 5248 ierr = ISCreateGeneral(PETSC_COMM_SELF,numRows,rows,&is);CHKERRQ(ierr); 5249 ierr = ISLocalToGlobalMappingApplyIS(mat->mapping,is,&newis);CHKERRQ(ierr); 5250 ierr = ISGetIndices(newis,&newRows);CHKERRQ(ierr); 5251 ierr = (*mat->ops->zerorows)(mat,numRows,newRows,diag);CHKERRQ(ierr); 5252 ierr = ISRestoreIndices(newis,&newRows);CHKERRQ(ierr); 5253 ierr = ISDestroy(newis);CHKERRQ(ierr); 5254 ierr = ISDestroy(is);CHKERRQ(ierr); 5255 } 5256 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5257 PetscFunctionReturn(0); 5258 } 5259 5260 #undef __FUNCT__ 5261 #define __FUNCT__ "MatZeroRowsLocalIS" 5262 /*@C 5263 MatZeroRowsLocalIS - Zeros all entries (except possibly the main diagonal) 5264 of a set of rows of a matrix; using local numbering of rows. 5265 5266 Collective on Mat 5267 5268 Input Parameters: 5269 + mat - the matrix 5270 . is - index set of rows to remove 5271 - diag - value put in all diagonals of eliminated rows 5272 5273 Notes: 5274 Before calling MatZeroRowsLocalIS(), the user must first set the 5275 local-to-global mapping by calling MatSetLocalToGlobalMapping(). 5276 5277 For the AIJ matrix formats this removes the old nonzero structure, 5278 but does not release memory. For the dense and block diagonal 5279 formats this does not alter the nonzero structure. 5280 5281 If the option MatSetOption(mat,MAT_KEEP_NONZERO_PATTERN,PETSC_TRUE) the nonzero structure 5282 of the matrix is not changed (even for AIJ and BAIJ matrices) the values are 5283 merely zeroed. 5284 5285 The user can set a value in the diagonal entry (or for the AIJ and 5286 row formats can optionally remove the main diagonal entry from the 5287 nonzero structure as well, by passing 0.0 as the final argument). 5288 5289 Level: intermediate 5290 5291 Concepts: matrices^zeroing 5292 5293 .seealso: MatZeroRows(), MatZeroRowsLocal(), MatZeroEntries(), MatZeroRows(), MatSetLocalToGlobalMapping 5294 @*/ 5295 PetscErrorCode PETSCMAT_DLLEXPORT MatZeroRowsLocalIS(Mat mat,IS is,PetscScalar diag) 5296 { 5297 PetscErrorCode ierr; 5298 PetscInt numRows; 5299 const PetscInt *rows; 5300 5301 PetscFunctionBegin; 5302 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5303 PetscValidType(mat,1); 5304 PetscValidHeaderSpecific(is,IS_CLASSID,2); 5305 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5306 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5307 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5308 5309 ierr = ISGetLocalSize(is,&numRows);CHKERRQ(ierr); 5310 ierr = ISGetIndices(is,&rows);CHKERRQ(ierr); 5311 ierr = MatZeroRowsLocal(mat,numRows,rows,diag);CHKERRQ(ierr); 5312 ierr = ISRestoreIndices(is,&rows);CHKERRQ(ierr); 5313 PetscFunctionReturn(0); 5314 } 5315 5316 #undef __FUNCT__ 5317 #define __FUNCT__ "MatGetSize" 5318 /*@ 5319 MatGetSize - Returns the numbers of rows and columns in a matrix. 5320 5321 Not Collective 5322 5323 Input Parameter: 5324 . mat - the matrix 5325 5326 Output Parameters: 5327 + m - the number of global rows 5328 - n - the number of global columns 5329 5330 Note: both output parameters can be PETSC_NULL on input. 5331 5332 Level: beginner 5333 5334 Concepts: matrices^size 5335 5336 .seealso: MatGetLocalSize() 5337 @*/ 5338 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSize(Mat mat,PetscInt *m,PetscInt* n) 5339 { 5340 PetscFunctionBegin; 5341 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5342 if (m) *m = mat->rmap->N; 5343 if (n) *n = mat->cmap->N; 5344 PetscFunctionReturn(0); 5345 } 5346 5347 #undef __FUNCT__ 5348 #define __FUNCT__ "MatGetLocalSize" 5349 /*@ 5350 MatGetLocalSize - Returns the number of rows and columns in a matrix 5351 stored locally. This information may be implementation dependent, so 5352 use with care. 5353 5354 Not Collective 5355 5356 Input Parameters: 5357 . mat - the matrix 5358 5359 Output Parameters: 5360 + m - the number of local rows 5361 - n - the number of local columns 5362 5363 Note: both output parameters can be PETSC_NULL on input. 5364 5365 Level: beginner 5366 5367 Concepts: matrices^local size 5368 5369 .seealso: MatGetSize() 5370 @*/ 5371 PetscErrorCode PETSCMAT_DLLEXPORT MatGetLocalSize(Mat mat,PetscInt *m,PetscInt* n) 5372 { 5373 PetscFunctionBegin; 5374 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5375 if (m) PetscValidIntPointer(m,2); 5376 if (n) PetscValidIntPointer(n,3); 5377 if (m) *m = mat->rmap->n; 5378 if (n) *n = mat->cmap->n; 5379 PetscFunctionReturn(0); 5380 } 5381 5382 #undef __FUNCT__ 5383 #define __FUNCT__ "MatGetOwnershipRangeColumn" 5384 /*@ 5385 MatGetOwnershipRangeColumn - Returns the range of matrix columns owned by 5386 this processor. 5387 5388 Not Collective, unless matrix has not been allocated, then collective on Mat 5389 5390 Input Parameters: 5391 . mat - the matrix 5392 5393 Output Parameters: 5394 + m - the global index of the first local column 5395 - n - one more than the global index of the last local column 5396 5397 Notes: both output parameters can be PETSC_NULL on input. 5398 5399 Level: developer 5400 5401 Concepts: matrices^column ownership 5402 5403 .seealso: MatGetOwnershipRange(), MatGetOwnershipRanges(), MatGetOwnershipRangesColumn() 5404 5405 @*/ 5406 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRangeColumn(Mat mat,PetscInt *m,PetscInt* n) 5407 { 5408 PetscErrorCode ierr; 5409 5410 PetscFunctionBegin; 5411 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5412 PetscValidType(mat,1); 5413 if (m) PetscValidIntPointer(m,2); 5414 if (n) PetscValidIntPointer(n,3); 5415 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5416 if (m) *m = mat->cmap->rstart; 5417 if (n) *n = mat->cmap->rend; 5418 PetscFunctionReturn(0); 5419 } 5420 5421 #undef __FUNCT__ 5422 #define __FUNCT__ "MatGetOwnershipRange" 5423 /*@ 5424 MatGetOwnershipRange - Returns the range of matrix rows owned by 5425 this processor, assuming that the matrix is laid out with the first 5426 n1 rows on the first processor, the next n2 rows on the second, etc. 5427 For certain parallel layouts this range may not be well defined. 5428 5429 Not Collective, unless matrix has not been allocated, then collective on Mat 5430 5431 Input Parameters: 5432 . mat - the matrix 5433 5434 Output Parameters: 5435 + m - the global index of the first local row 5436 - n - one more than the global index of the last local row 5437 5438 Note: both output parameters can be PETSC_NULL on input. 5439 5440 Level: beginner 5441 5442 Concepts: matrices^row ownership 5443 5444 .seealso: MatGetOwnershipRanges(), MatGetOwnershipRangeColumn(), MatGetOwnershipRangesColumn() 5445 5446 @*/ 5447 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRange(Mat mat,PetscInt *m,PetscInt* n) 5448 { 5449 PetscErrorCode ierr; 5450 5451 PetscFunctionBegin; 5452 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5453 PetscValidType(mat,1); 5454 if (m) PetscValidIntPointer(m,2); 5455 if (n) PetscValidIntPointer(n,3); 5456 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5457 if (m) *m = mat->rmap->rstart; 5458 if (n) *n = mat->rmap->rend; 5459 PetscFunctionReturn(0); 5460 } 5461 5462 #undef __FUNCT__ 5463 #define __FUNCT__ "MatGetOwnershipRanges" 5464 /*@C 5465 MatGetOwnershipRanges - Returns the range of matrix rows owned by 5466 each process 5467 5468 Not Collective, unless matrix has not been allocated, then collective on Mat 5469 5470 Input Parameters: 5471 . mat - the matrix 5472 5473 Output Parameters: 5474 . ranges - start of each processors portion plus one more then the total length at the end 5475 5476 Level: beginner 5477 5478 Concepts: matrices^row ownership 5479 5480 .seealso: MatGetOwnershipRange(), MatGetOwnershipRangeColumn(), MatGetOwnershipRangesColumn() 5481 5482 @*/ 5483 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRanges(Mat mat,const PetscInt **ranges) 5484 { 5485 PetscErrorCode ierr; 5486 5487 PetscFunctionBegin; 5488 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5489 PetscValidType(mat,1); 5490 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5491 ierr = PetscLayoutGetRanges(mat->rmap,ranges);CHKERRQ(ierr); 5492 PetscFunctionReturn(0); 5493 } 5494 5495 #undef __FUNCT__ 5496 #define __FUNCT__ "MatGetOwnershipRangesColumn" 5497 /*@C 5498 MatGetOwnershipRangesColumn - Returns the range of local columns for each process 5499 5500 Not Collective, unless matrix has not been allocated, then collective on Mat 5501 5502 Input Parameters: 5503 . mat - the matrix 5504 5505 Output Parameters: 5506 . ranges - start of each processors portion plus one more then the total length at the end 5507 5508 Level: beginner 5509 5510 Concepts: matrices^column ownership 5511 5512 .seealso: MatGetOwnershipRange(), MatGetOwnershipRangeColumn(), MatGetOwnershipRanges() 5513 5514 @*/ 5515 PetscErrorCode PETSCMAT_DLLEXPORT MatGetOwnershipRangesColumn(Mat mat,const PetscInt **ranges) 5516 { 5517 PetscErrorCode ierr; 5518 5519 PetscFunctionBegin; 5520 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5521 PetscValidType(mat,1); 5522 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5523 ierr = PetscLayoutGetRanges(mat->cmap,ranges);CHKERRQ(ierr); 5524 PetscFunctionReturn(0); 5525 } 5526 5527 #undef __FUNCT__ 5528 #define __FUNCT__ "MatILUFactorSymbolic" 5529 /*@C 5530 MatILUFactorSymbolic - Performs symbolic ILU factorization of a matrix. 5531 Uses levels of fill only, not drop tolerance. Use MatLUFactorNumeric() 5532 to complete the factorization. 5533 5534 Collective on Mat 5535 5536 Input Parameters: 5537 + mat - the matrix 5538 . row - row permutation 5539 . column - column permutation 5540 - info - structure containing 5541 $ levels - number of levels of fill. 5542 $ expected fill - as ratio of original fill. 5543 $ 1 or 0 - indicating force fill on diagonal (improves robustness for matrices 5544 missing diagonal entries) 5545 5546 Output Parameters: 5547 . fact - new matrix that has been symbolically factored 5548 5549 Notes: 5550 See the users manual for additional information about 5551 choosing the fill factor for better efficiency. 5552 5553 Most users should employ the simplified KSP interface for linear solvers 5554 instead of working directly with matrix algebra routines such as this. 5555 See, e.g., KSPCreate(). 5556 5557 Level: developer 5558 5559 Concepts: matrices^symbolic LU factorization 5560 Concepts: matrices^factorization 5561 Concepts: LU^symbolic factorization 5562 5563 .seealso: MatLUFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 5564 MatGetOrdering(), MatFactorInfo 5565 5566 Developer Note: fortran interface is not autogenerated as the f90 5567 interface defintion cannot be generated correctly [due to MatFactorInfo] 5568 5569 @*/ 5570 PetscErrorCode PETSCMAT_DLLEXPORT MatILUFactorSymbolic(Mat fact,Mat mat,IS row,IS col,const MatFactorInfo *info) 5571 { 5572 PetscErrorCode ierr; 5573 5574 PetscFunctionBegin; 5575 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5576 PetscValidType(mat,1); 5577 PetscValidHeaderSpecific(row,IS_CLASSID,2); 5578 PetscValidHeaderSpecific(col,IS_CLASSID,3); 5579 PetscValidPointer(info,4); 5580 PetscValidPointer(fact,5); 5581 if (info->levels < 0) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Levels of fill negative %D",(PetscInt)info->levels); 5582 if (info->fill < 1.0) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 5583 if (!(fact)->ops->ilufactorsymbolic) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Matrix type %s symbolic ILU",((PetscObject)mat)->type_name); 5584 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5585 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5586 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5587 5588 ierr = PetscLogEventBegin(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 5589 ierr = (fact->ops->ilufactorsymbolic)(fact,mat,row,col,info);CHKERRQ(ierr); 5590 ierr = PetscLogEventEnd(MAT_ILUFactorSymbolic,mat,row,col,0);CHKERRQ(ierr); 5591 PetscFunctionReturn(0); 5592 } 5593 5594 #undef __FUNCT__ 5595 #define __FUNCT__ "MatICCFactorSymbolic" 5596 /*@C 5597 MatICCFactorSymbolic - Performs symbolic incomplete 5598 Cholesky factorization for a symmetric matrix. Use 5599 MatCholeskyFactorNumeric() to complete the factorization. 5600 5601 Collective on Mat 5602 5603 Input Parameters: 5604 + mat - the matrix 5605 . perm - row and column permutation 5606 - info - structure containing 5607 $ levels - number of levels of fill. 5608 $ expected fill - as ratio of original fill. 5609 5610 Output Parameter: 5611 . fact - the factored matrix 5612 5613 Notes: 5614 Most users should employ the KSP interface for linear solvers 5615 instead of working directly with matrix algebra routines such as this. 5616 See, e.g., KSPCreate(). 5617 5618 Level: developer 5619 5620 Concepts: matrices^symbolic incomplete Cholesky factorization 5621 Concepts: matrices^factorization 5622 Concepts: Cholsky^symbolic factorization 5623 5624 .seealso: MatCholeskyFactorNumeric(), MatCholeskyFactor(), MatFactorInfo 5625 5626 Developer Note: fortran interface is not autogenerated as the f90 5627 interface defintion cannot be generated correctly [due to MatFactorInfo] 5628 5629 @*/ 5630 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactorSymbolic(Mat fact,Mat mat,IS perm,const MatFactorInfo *info) 5631 { 5632 PetscErrorCode ierr; 5633 5634 PetscFunctionBegin; 5635 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5636 PetscValidType(mat,1); 5637 PetscValidHeaderSpecific(perm,IS_CLASSID,2); 5638 PetscValidPointer(info,3); 5639 PetscValidPointer(fact,4); 5640 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5641 if (info->levels < 0) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Levels negative %D",(PetscInt) info->levels); 5642 if (info->fill < 1.0) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Expected fill less than 1.0 %G",info->fill); 5643 if (!(fact)->ops->iccfactorsymbolic) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Matrix type %s symbolic ICC",((PetscObject)mat)->type_name); 5644 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5645 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5646 5647 ierr = PetscLogEventBegin(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 5648 ierr = (fact->ops->iccfactorsymbolic)(fact,mat,perm,info);CHKERRQ(ierr); 5649 ierr = PetscLogEventEnd(MAT_ICCFactorSymbolic,mat,perm,0,0);CHKERRQ(ierr); 5650 PetscFunctionReturn(0); 5651 } 5652 5653 #undef __FUNCT__ 5654 #define __FUNCT__ "MatGetArray" 5655 /*@C 5656 MatGetArray - Returns a pointer to the element values in the matrix. 5657 The result of this routine is dependent on the underlying matrix data 5658 structure, and may not even work for certain matrix types. You MUST 5659 call MatRestoreArray() when you no longer need to access the array. 5660 5661 Not Collective 5662 5663 Input Parameter: 5664 . mat - the matrix 5665 5666 Output Parameter: 5667 . v - the location of the values 5668 5669 5670 Fortran Note: 5671 This routine is used differently from Fortran, e.g., 5672 .vb 5673 Mat mat 5674 PetscScalar mat_array(1) 5675 PetscOffset i_mat 5676 PetscErrorCode ierr 5677 call MatGetArray(mat,mat_array,i_mat,ierr) 5678 5679 C Access first local entry in matrix; note that array is 5680 C treated as one dimensional 5681 value = mat_array(i_mat + 1) 5682 5683 [... other code ...] 5684 call MatRestoreArray(mat,mat_array,i_mat,ierr) 5685 .ve 5686 5687 See the Fortran chapter of the users manual and 5688 petsc/src/mat/examples/tests for details. 5689 5690 Level: advanced 5691 5692 Concepts: matrices^access array 5693 5694 .seealso: MatRestoreArray(), MatGetArrayF90(), MatGetRowIJ() 5695 @*/ 5696 PetscErrorCode PETSCMAT_DLLEXPORT MatGetArray(Mat mat,PetscScalar *v[]) 5697 { 5698 PetscErrorCode ierr; 5699 5700 PetscFunctionBegin; 5701 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5702 PetscValidType(mat,1); 5703 PetscValidPointer(v,2); 5704 if (!mat->ops->getarray) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5705 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5706 ierr = (*mat->ops->getarray)(mat,v);CHKERRQ(ierr); 5707 CHKMEMQ; 5708 PetscFunctionReturn(0); 5709 } 5710 5711 #undef __FUNCT__ 5712 #define __FUNCT__ "MatRestoreArray" 5713 /*@C 5714 MatRestoreArray - Restores the matrix after MatGetArray() has been called. 5715 5716 Not Collective 5717 5718 Input Parameter: 5719 + mat - the matrix 5720 - v - the location of the values 5721 5722 Fortran Note: 5723 This routine is used differently from Fortran, e.g., 5724 .vb 5725 Mat mat 5726 PetscScalar mat_array(1) 5727 PetscOffset i_mat 5728 PetscErrorCode ierr 5729 call MatGetArray(mat,mat_array,i_mat,ierr) 5730 5731 C Access first local entry in matrix; note that array is 5732 C treated as one dimensional 5733 value = mat_array(i_mat + 1) 5734 5735 [... other code ...] 5736 call MatRestoreArray(mat,mat_array,i_mat,ierr) 5737 .ve 5738 5739 See the Fortran chapter of the users manual and 5740 petsc/src/mat/examples/tests for details 5741 5742 Level: advanced 5743 5744 .seealso: MatGetArray(), MatRestoreArrayF90() 5745 @*/ 5746 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreArray(Mat mat,PetscScalar *v[]) 5747 { 5748 PetscErrorCode ierr; 5749 5750 PetscFunctionBegin; 5751 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5752 PetscValidType(mat,1); 5753 PetscValidPointer(v,2); 5754 #if defined(PETSC_USE_DEBUG) 5755 CHKMEMQ; 5756 #endif 5757 if (!mat->ops->restorearray) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5758 ierr = (*mat->ops->restorearray)(mat,v);CHKERRQ(ierr); 5759 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 5760 PetscFunctionReturn(0); 5761 } 5762 5763 #undef __FUNCT__ 5764 #define __FUNCT__ "MatGetSubMatrices" 5765 /*@C 5766 MatGetSubMatrices - Extracts several submatrices from a matrix. If submat 5767 points to an array of valid matrices, they may be reused to store the new 5768 submatrices. 5769 5770 Collective on Mat 5771 5772 Input Parameters: 5773 + mat - the matrix 5774 . n - the number of submatrixes to be extracted (on this processor, may be zero) 5775 . irow, icol - index sets of rows and columns to extract 5776 - scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 5777 5778 Output Parameter: 5779 . submat - the array of submatrices 5780 5781 Notes: 5782 MatGetSubMatrices() can extract ONLY sequential submatrices 5783 (from both sequential and parallel matrices). Use MatGetSubMatrix() 5784 to extract a parallel submatrix. 5785 5786 When extracting submatrices from a parallel matrix, each processor can 5787 form a different submatrix by setting the rows and columns of its 5788 individual index sets according to the local submatrix desired. 5789 5790 When finished using the submatrices, the user should destroy 5791 them with MatDestroyMatrices(). 5792 5793 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 5794 original matrix has not changed from that last call to MatGetSubMatrices(). 5795 5796 This routine creates the matrices in submat; you should NOT create them before 5797 calling it. It also allocates the array of matrix pointers submat. 5798 5799 For BAIJ matrices the index sets must respect the block structure, that is if they 5800 request one row/column in a block, they must request all rows/columns that are in 5801 that block. For example, if the block size is 2 you cannot request just row 0 and 5802 column 0. 5803 5804 Fortran Note: 5805 The Fortran interface is slightly different from that given below; it 5806 requires one to pass in as submat a Mat (integer) array of size at least m. 5807 5808 Level: advanced 5809 5810 Concepts: matrices^accessing submatrices 5811 Concepts: submatrices 5812 5813 .seealso: MatDestroyMatrices(), MatGetSubMatrix(), MatGetRow(), MatGetDiagonal(), MatReuse 5814 @*/ 5815 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrices(Mat mat,PetscInt n,const IS irow[],const IS icol[],MatReuse scall,Mat *submat[]) 5816 { 5817 PetscErrorCode ierr; 5818 PetscInt i; 5819 PetscTruth eq; 5820 5821 PetscFunctionBegin; 5822 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5823 PetscValidType(mat,1); 5824 if (n) { 5825 PetscValidPointer(irow,3); 5826 PetscValidHeaderSpecific(*irow,IS_CLASSID,3); 5827 PetscValidPointer(icol,4); 5828 PetscValidHeaderSpecific(*icol,IS_CLASSID,4); 5829 } 5830 PetscValidPointer(submat,6); 5831 if (n && scall == MAT_REUSE_MATRIX) { 5832 PetscValidPointer(*submat,6); 5833 PetscValidHeaderSpecific(**submat,MAT_CLASSID,6); 5834 } 5835 if (!mat->ops->getsubmatrices) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5836 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5837 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5838 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5839 5840 ierr = PetscLogEventBegin(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 5841 ierr = (*mat->ops->getsubmatrices)(mat,n,irow,icol,scall,submat);CHKERRQ(ierr); 5842 ierr = PetscLogEventEnd(MAT_GetSubMatrices,mat,0,0,0);CHKERRQ(ierr); 5843 for (i=0; i<n; i++) { 5844 if (mat->symmetric || mat->structurally_symmetric || mat->hermitian) { 5845 ierr = ISEqual(irow[i],icol[i],&eq);CHKERRQ(ierr); 5846 if (eq) { 5847 if (mat->symmetric){ 5848 ierr = MatSetOption((*submat)[i],MAT_SYMMETRIC,PETSC_TRUE);CHKERRQ(ierr); 5849 } else if (mat->hermitian) { 5850 ierr = MatSetOption((*submat)[i],MAT_HERMITIAN,PETSC_TRUE);CHKERRQ(ierr); 5851 } else if (mat->structurally_symmetric) { 5852 ierr = MatSetOption((*submat)[i],MAT_STRUCTURALLY_SYMMETRIC,PETSC_TRUE);CHKERRQ(ierr); 5853 } 5854 } 5855 } 5856 } 5857 PetscFunctionReturn(0); 5858 } 5859 5860 #undef __FUNCT__ 5861 #define __FUNCT__ "MatDestroyMatrices" 5862 /*@C 5863 MatDestroyMatrices - Destroys a set of matrices obtained with MatGetSubMatrices(). 5864 5865 Collective on Mat 5866 5867 Input Parameters: 5868 + n - the number of local matrices 5869 - mat - the matrices (note that this is a pointer to the array of matrices, just to match the calling 5870 sequence of MatGetSubMatrices()) 5871 5872 Level: advanced 5873 5874 Notes: Frees not only the matrices, but also the array that contains the matrices 5875 In Fortran will not free the array. 5876 5877 .seealso: MatGetSubMatrices() 5878 @*/ 5879 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroyMatrices(PetscInt n,Mat *mat[]) 5880 { 5881 PetscErrorCode ierr; 5882 PetscInt i; 5883 5884 PetscFunctionBegin; 5885 if (n < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of matrices %D",n); 5886 PetscValidPointer(mat,2); 5887 for (i=0; i<n; i++) { 5888 ierr = MatDestroy((*mat)[i]);CHKERRQ(ierr); 5889 } 5890 /* memory is allocated even if n = 0 */ 5891 ierr = PetscFree(*mat);CHKERRQ(ierr); 5892 PetscFunctionReturn(0); 5893 } 5894 5895 #undef __FUNCT__ 5896 #define __FUNCT__ "MatGetSeqNonzeroStructure" 5897 /*@C 5898 MatGetSeqNonzeroStructure - Extracts the sequential nonzero structure from a matrix. 5899 5900 Collective on Mat 5901 5902 Input Parameters: 5903 . mat - the matrix 5904 5905 Output Parameter: 5906 . matstruct - the sequential matrix with the nonzero structure of mat 5907 5908 Level: intermediate 5909 5910 .seealso: MatDestroySeqNonzeroStructure(), MatGetSubMatrices(), MatDestroyMatrices() 5911 @*/ 5912 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSeqNonzeroStructure(Mat mat,Mat *matstruct) 5913 { 5914 PetscErrorCode ierr; 5915 5916 PetscFunctionBegin; 5917 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5918 PetscValidPointer(matstruct,2); 5919 5920 PetscValidType(mat,1); 5921 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5922 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5923 5924 if (!mat->ops->getseqnonzerostructure) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Not for matrix type %s\n",((PetscObject)mat)->type_name); 5925 ierr = PetscLogEventBegin(MAT_GetSeqNonzeroStructure,mat,0,0,0);CHKERRQ(ierr); 5926 ierr = (*mat->ops->getseqnonzerostructure)(mat,matstruct);CHKERRQ(ierr); 5927 ierr = PetscLogEventEnd(MAT_GetSeqNonzeroStructure,mat,0,0,0);CHKERRQ(ierr); 5928 PetscFunctionReturn(0); 5929 } 5930 5931 #undef __FUNCT__ 5932 #define __FUNCT__ "MatDestroySeqNonzeroStructure" 5933 /*@C 5934 MatDestroySeqNonzeroStructure - Destroys matrix obtained with MatGetSeqNonzeroStructure(). 5935 5936 Collective on Mat 5937 5938 Input Parameters: 5939 . mat - the matrix (note that this is a pointer to the array of matrices, just to match the calling 5940 sequence of MatGetSequentialNonzeroStructure()) 5941 5942 Level: advanced 5943 5944 Notes: Frees not only the matrices, but also the array that contains the matrices 5945 5946 .seealso: MatGetSeqNonzeroStructure() 5947 @*/ 5948 PetscErrorCode PETSCMAT_DLLEXPORT MatDestroySeqNonzeroStructure(Mat *mat) 5949 { 5950 PetscErrorCode ierr; 5951 5952 PetscFunctionBegin; 5953 PetscValidPointer(mat,1); 5954 ierr = MatDestroy(*mat);CHKERRQ(ierr); 5955 PetscFunctionReturn(0); 5956 } 5957 5958 #undef __FUNCT__ 5959 #define __FUNCT__ "MatIncreaseOverlap" 5960 /*@ 5961 MatIncreaseOverlap - Given a set of submatrices indicated by index sets, 5962 replaces the index sets by larger ones that represent submatrices with 5963 additional overlap. 5964 5965 Collective on Mat 5966 5967 Input Parameters: 5968 + mat - the matrix 5969 . n - the number of index sets 5970 . is - the array of index sets (these index sets will changed during the call) 5971 - ov - the additional overlap requested 5972 5973 Level: developer 5974 5975 Concepts: overlap 5976 Concepts: ASM^computing overlap 5977 5978 .seealso: MatGetSubMatrices() 5979 @*/ 5980 PetscErrorCode PETSCMAT_DLLEXPORT MatIncreaseOverlap(Mat mat,PetscInt n,IS is[],PetscInt ov) 5981 { 5982 PetscErrorCode ierr; 5983 5984 PetscFunctionBegin; 5985 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 5986 PetscValidType(mat,1); 5987 if (n < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more domains, you have %D",n); 5988 if (n) { 5989 PetscValidPointer(is,3); 5990 PetscValidHeaderSpecific(*is,IS_CLASSID,3); 5991 } 5992 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 5993 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 5994 ierr = MatPreallocated(mat);CHKERRQ(ierr); 5995 5996 if (!ov) PetscFunctionReturn(0); 5997 if (!mat->ops->increaseoverlap) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 5998 ierr = PetscLogEventBegin(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 5999 ierr = (*mat->ops->increaseoverlap)(mat,n,is,ov);CHKERRQ(ierr); 6000 ierr = PetscLogEventEnd(MAT_IncreaseOverlap,mat,0,0,0);CHKERRQ(ierr); 6001 PetscFunctionReturn(0); 6002 } 6003 6004 #undef __FUNCT__ 6005 #define __FUNCT__ "MatGetBlockSize" 6006 /*@ 6007 MatGetBlockSize - Returns the matrix block size; useful especially for the 6008 block row and block diagonal formats. 6009 6010 Not Collective 6011 6012 Input Parameter: 6013 . mat - the matrix 6014 6015 Output Parameter: 6016 . bs - block size 6017 6018 Notes: 6019 Block row formats are MATSEQBAIJ, MATMPIBAIJ, MATSEQSBAIJ, MATMPISBAIJ 6020 6021 Level: intermediate 6022 6023 Concepts: matrices^block size 6024 6025 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ() 6026 @*/ 6027 PetscErrorCode PETSCMAT_DLLEXPORT MatGetBlockSize(Mat mat,PetscInt *bs) 6028 { 6029 PetscErrorCode ierr; 6030 6031 PetscFunctionBegin; 6032 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6033 PetscValidType(mat,1); 6034 PetscValidIntPointer(bs,2); 6035 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6036 *bs = mat->rmap->bs; 6037 PetscFunctionReturn(0); 6038 } 6039 6040 #undef __FUNCT__ 6041 #define __FUNCT__ "MatSetBlockSize" 6042 /*@ 6043 MatSetBlockSize - Sets the matrix block size; for many matrix types you 6044 cannot use this and MUST set the blocksize when you preallocate the matrix 6045 6046 Collective on Mat 6047 6048 Input Parameters: 6049 + mat - the matrix 6050 - bs - block size 6051 6052 Notes: 6053 For BAIJ matrices, this just checks that the block size agrees with the BAIJ size, 6054 it is not possible to change BAIJ block sizes after preallocation. 6055 6056 Level: intermediate 6057 6058 Concepts: matrices^block size 6059 6060 .seealso: MatCreateSeqBAIJ(), MatCreateMPIBAIJ(), MatGetBlockSize() 6061 @*/ 6062 PetscErrorCode PETSCMAT_DLLEXPORT MatSetBlockSize(Mat mat,PetscInt bs) 6063 { 6064 PetscErrorCode ierr; 6065 6066 PetscFunctionBegin; 6067 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6068 PetscValidType(mat,1); 6069 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6070 if (bs < 1) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Block size %d, must be positive",bs); 6071 if (mat->ops->setblocksize) { 6072 ierr = (*mat->ops->setblocksize)(mat,bs);CHKERRQ(ierr); 6073 } else { 6074 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Cannot set the blocksize for matrix type %s",((PetscObject)mat)->type_name); 6075 } 6076 PetscFunctionReturn(0); 6077 } 6078 6079 #undef __FUNCT__ 6080 #define __FUNCT__ "MatGetRowIJ" 6081 /*@C 6082 MatGetRowIJ - Returns the compressed row storage i and j indices for sequential matrices. 6083 6084 Collective on Mat 6085 6086 Input Parameters: 6087 + mat - the matrix 6088 . shift - 0 or 1 indicating we want the indices starting at 0 or 1 6089 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6090 symmetrized 6091 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6092 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6093 always used. 6094 6095 Output Parameters: 6096 + n - number of rows in the (possibly compressed) matrix 6097 . ia - the row pointers [of length n+1] 6098 . ja - the column indices 6099 - done - indicates if the routine actually worked and returned appropriate ia[] and ja[] arrays; callers 6100 are responsible for handling the case when done == PETSC_FALSE and ia and ja are not set 6101 6102 Level: developer 6103 6104 Notes: You CANNOT change any of the ia[] or ja[] values. 6105 6106 Use MatRestoreRowIJ() when you are finished accessing the ia[] and ja[] values 6107 6108 Fortran Node 6109 6110 In Fortran use 6111 $ PetscInt ia(1), ja(1) 6112 $ PetscOffset iia, jja 6113 $ call MatGetRowIJ(mat,shift,symmetric,inodecompressed,n,ia,iia,ja,jja,done,ierr) 6114 $ 6115 $ or 6116 $ 6117 $ PetscScalar, pointer :: xx_v(:) 6118 $ call MatGetRowIJF90(mat,shift,symmetric,inodecompressed,n,ia,ja,done,ierr) 6119 6120 6121 Acess the ith and jth entries via ia(iia + i) and ja(jja + j) 6122 6123 .seealso: MatGetColumnIJ(), MatRestoreRowIJ(), MatGetArray() 6124 @*/ 6125 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6126 { 6127 PetscErrorCode ierr; 6128 6129 PetscFunctionBegin; 6130 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6131 PetscValidType(mat,1); 6132 PetscValidIntPointer(n,4); 6133 if (ia) PetscValidIntPointer(ia,5); 6134 if (ja) PetscValidIntPointer(ja,6); 6135 PetscValidIntPointer(done,7); 6136 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6137 if (!mat->ops->getrowij) *done = PETSC_FALSE; 6138 else { 6139 *done = PETSC_TRUE; 6140 ierr = PetscLogEventBegin(MAT_GetRowIJ,mat,0,0,0);CHKERRQ(ierr); 6141 ierr = (*mat->ops->getrowij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6142 ierr = PetscLogEventEnd(MAT_GetRowIJ,mat,0,0,0);CHKERRQ(ierr); 6143 } 6144 PetscFunctionReturn(0); 6145 } 6146 6147 #undef __FUNCT__ 6148 #define __FUNCT__ "MatGetColumnIJ" 6149 /*@C 6150 MatGetColumnIJ - Returns the compressed column storage i and j indices for sequential matrices. 6151 6152 Collective on Mat 6153 6154 Input Parameters: 6155 + mat - the matrix 6156 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6157 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6158 symmetrized 6159 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6160 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6161 always used. 6162 6163 Output Parameters: 6164 + n - number of columns in the (possibly compressed) matrix 6165 . ia - the column pointers 6166 . ja - the row indices 6167 - done - PETSC_TRUE or PETSC_FALSE, indicating whether the values have been returned 6168 6169 Level: developer 6170 6171 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 6172 @*/ 6173 PetscErrorCode PETSCMAT_DLLEXPORT MatGetColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6174 { 6175 PetscErrorCode ierr; 6176 6177 PetscFunctionBegin; 6178 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6179 PetscValidType(mat,1); 6180 PetscValidIntPointer(n,4); 6181 if (ia) PetscValidIntPointer(ia,5); 6182 if (ja) PetscValidIntPointer(ja,6); 6183 PetscValidIntPointer(done,7); 6184 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6185 if (!mat->ops->getcolumnij) *done = PETSC_FALSE; 6186 else { 6187 *done = PETSC_TRUE; 6188 ierr = (*mat->ops->getcolumnij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6189 } 6190 PetscFunctionReturn(0); 6191 } 6192 6193 #undef __FUNCT__ 6194 #define __FUNCT__ "MatRestoreRowIJ" 6195 /*@C 6196 MatRestoreRowIJ - Call after you are completed with the ia,ja indices obtained with 6197 MatGetRowIJ(). 6198 6199 Collective on Mat 6200 6201 Input Parameters: 6202 + mat - the matrix 6203 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6204 . symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6205 symmetrized 6206 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6207 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6208 always used. 6209 6210 Output Parameters: 6211 + n - size of (possibly compressed) matrix 6212 . ia - the row pointers 6213 . ja - the column indices 6214 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 6215 6216 Level: developer 6217 6218 .seealso: MatGetRowIJ(), MatRestoreColumnIJ() 6219 @*/ 6220 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreRowIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6221 { 6222 PetscErrorCode ierr; 6223 6224 PetscFunctionBegin; 6225 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6226 PetscValidType(mat,1); 6227 if (ia) PetscValidIntPointer(ia,5); 6228 if (ja) PetscValidIntPointer(ja,6); 6229 PetscValidIntPointer(done,7); 6230 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6231 6232 if (!mat->ops->restorerowij) *done = PETSC_FALSE; 6233 else { 6234 *done = PETSC_TRUE; 6235 ierr = (*mat->ops->restorerowij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6236 } 6237 PetscFunctionReturn(0); 6238 } 6239 6240 #undef __FUNCT__ 6241 #define __FUNCT__ "MatRestoreColumnIJ" 6242 /*@C 6243 MatRestoreColumnIJ - Call after you are completed with the ia,ja indices obtained with 6244 MatGetColumnIJ(). 6245 6246 Collective on Mat 6247 6248 Input Parameters: 6249 + mat - the matrix 6250 . shift - 1 or zero indicating we want the indices starting at 0 or 1 6251 - symmetric - PETSC_TRUE or PETSC_FALSE indicating the matrix data structure should be 6252 symmetrized 6253 - inodecompressed - PETSC_TRUE or PETSC_FALSE indicating if the nonzero structure of the 6254 inodes or the nonzero elements is wanted. For BAIJ matrices the compressed version is 6255 always used. 6256 6257 Output Parameters: 6258 + n - size of (possibly compressed) matrix 6259 . ia - the column pointers 6260 . ja - the row indices 6261 - done - PETSC_TRUE or PETSC_FALSE indicated that the values have been returned 6262 6263 Level: developer 6264 6265 .seealso: MatGetColumnIJ(), MatRestoreRowIJ() 6266 @*/ 6267 PetscErrorCode PETSCMAT_DLLEXPORT MatRestoreColumnIJ(Mat mat,PetscInt shift,PetscTruth symmetric,PetscTruth inodecompressed,PetscInt *n,PetscInt *ia[],PetscInt* ja[],PetscTruth *done) 6268 { 6269 PetscErrorCode ierr; 6270 6271 PetscFunctionBegin; 6272 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6273 PetscValidType(mat,1); 6274 if (ia) PetscValidIntPointer(ia,5); 6275 if (ja) PetscValidIntPointer(ja,6); 6276 PetscValidIntPointer(done,7); 6277 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6278 6279 if (!mat->ops->restorecolumnij) *done = PETSC_FALSE; 6280 else { 6281 *done = PETSC_TRUE; 6282 ierr = (*mat->ops->restorecolumnij)(mat,shift,symmetric,inodecompressed,n,ia,ja,done);CHKERRQ(ierr); 6283 } 6284 PetscFunctionReturn(0); 6285 } 6286 6287 #undef __FUNCT__ 6288 #define __FUNCT__ "MatColoringPatch" 6289 /*@C 6290 MatColoringPatch -Used inside matrix coloring routines that 6291 use MatGetRowIJ() and/or MatGetColumnIJ(). 6292 6293 Collective on Mat 6294 6295 Input Parameters: 6296 + mat - the matrix 6297 . ncolors - max color value 6298 . n - number of entries in colorarray 6299 - colorarray - array indicating color for each column 6300 6301 Output Parameters: 6302 . iscoloring - coloring generated using colorarray information 6303 6304 Level: developer 6305 6306 .seealso: MatGetRowIJ(), MatGetColumnIJ() 6307 6308 @*/ 6309 PetscErrorCode PETSCMAT_DLLEXPORT MatColoringPatch(Mat mat,PetscInt ncolors,PetscInt n,ISColoringValue colorarray[],ISColoring *iscoloring) 6310 { 6311 PetscErrorCode ierr; 6312 6313 PetscFunctionBegin; 6314 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6315 PetscValidType(mat,1); 6316 PetscValidIntPointer(colorarray,4); 6317 PetscValidPointer(iscoloring,5); 6318 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6319 6320 if (!mat->ops->coloringpatch){ 6321 ierr = ISColoringCreate(((PetscObject)mat)->comm,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 6322 } else { 6323 ierr = (*mat->ops->coloringpatch)(mat,ncolors,n,colorarray,iscoloring);CHKERRQ(ierr); 6324 } 6325 PetscFunctionReturn(0); 6326 } 6327 6328 6329 #undef __FUNCT__ 6330 #define __FUNCT__ "MatSetUnfactored" 6331 /*@ 6332 MatSetUnfactored - Resets a factored matrix to be treated as unfactored. 6333 6334 Collective on Mat 6335 6336 Input Parameter: 6337 . mat - the factored matrix to be reset 6338 6339 Notes: 6340 This routine should be used only with factored matrices formed by in-place 6341 factorization via ILU(0) (or by in-place LU factorization for the MATSEQDENSE 6342 format). This option can save memory, for example, when solving nonlinear 6343 systems with a matrix-free Newton-Krylov method and a matrix-based, in-place 6344 ILU(0) preconditioner. 6345 6346 Note that one can specify in-place ILU(0) factorization by calling 6347 .vb 6348 PCType(pc,PCILU); 6349 PCFactorSeUseInPlace(pc); 6350 .ve 6351 or by using the options -pc_type ilu -pc_factor_in_place 6352 6353 In-place factorization ILU(0) can also be used as a local 6354 solver for the blocks within the block Jacobi or additive Schwarz 6355 methods (runtime option: -sub_pc_factor_in_place). See the discussion 6356 of these preconditioners in the users manual for details on setting 6357 local solver options. 6358 6359 Most users should employ the simplified KSP interface for linear solvers 6360 instead of working directly with matrix algebra routines such as this. 6361 See, e.g., KSPCreate(). 6362 6363 Level: developer 6364 6365 .seealso: PCFactorSetUseInPlace() 6366 6367 Concepts: matrices^unfactored 6368 6369 @*/ 6370 PetscErrorCode PETSCMAT_DLLEXPORT MatSetUnfactored(Mat mat) 6371 { 6372 PetscErrorCode ierr; 6373 6374 PetscFunctionBegin; 6375 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6376 PetscValidType(mat,1); 6377 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6378 mat->factortype = MAT_FACTOR_NONE; 6379 if (!mat->ops->setunfactored) PetscFunctionReturn(0); 6380 ierr = (*mat->ops->setunfactored)(mat);CHKERRQ(ierr); 6381 PetscFunctionReturn(0); 6382 } 6383 6384 /*MC 6385 MatGetArrayF90 - Accesses a matrix array from Fortran90. 6386 6387 Synopsis: 6388 MatGetArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 6389 6390 Not collective 6391 6392 Input Parameter: 6393 . x - matrix 6394 6395 Output Parameters: 6396 + xx_v - the Fortran90 pointer to the array 6397 - ierr - error code 6398 6399 Example of Usage: 6400 .vb 6401 PetscScalar, pointer xx_v(:) 6402 .... 6403 call MatGetArrayF90(x,xx_v,ierr) 6404 a = xx_v(3) 6405 call MatRestoreArrayF90(x,xx_v,ierr) 6406 .ve 6407 6408 Notes: 6409 Not yet supported for all F90 compilers 6410 6411 Level: advanced 6412 6413 .seealso: MatRestoreArrayF90(), MatGetArray(), MatRestoreArray() 6414 6415 Concepts: matrices^accessing array 6416 6417 M*/ 6418 6419 /*MC 6420 MatRestoreArrayF90 - Restores a matrix array that has been 6421 accessed with MatGetArrayF90(). 6422 6423 Synopsis: 6424 MatRestoreArrayF90(Mat x,{Scalar, pointer :: xx_v(:)},integer ierr) 6425 6426 Not collective 6427 6428 Input Parameters: 6429 + x - matrix 6430 - xx_v - the Fortran90 pointer to the array 6431 6432 Output Parameter: 6433 . ierr - error code 6434 6435 Example of Usage: 6436 .vb 6437 PetscScalar, pointer xx_v(:) 6438 .... 6439 call MatGetArrayF90(x,xx_v,ierr) 6440 a = xx_v(3) 6441 call MatRestoreArrayF90(x,xx_v,ierr) 6442 .ve 6443 6444 Notes: 6445 Not yet supported for all F90 compilers 6446 6447 Level: advanced 6448 6449 .seealso: MatGetArrayF90(), MatGetArray(), MatRestoreArray() 6450 6451 M*/ 6452 6453 6454 #undef __FUNCT__ 6455 #define __FUNCT__ "MatGetSubMatrix" 6456 /*@ 6457 MatGetSubMatrix - Gets a single submatrix on the same number of processors 6458 as the original matrix. 6459 6460 Collective on Mat 6461 6462 Input Parameters: 6463 + mat - the original matrix 6464 . isrow - parallel IS containing the rows this processor should obtain 6465 . 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. 6466 - cll - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 6467 6468 Output Parameter: 6469 . newmat - the new submatrix, of the same type as the old 6470 6471 Level: advanced 6472 6473 Notes: 6474 The submatrix will be able to be multiplied with vectors using the same layout as iscol. 6475 6476 The rows in isrow will be sorted into the same order as the original matrix on each process. 6477 6478 The first time this is called you should use a cll of MAT_INITIAL_MATRIX, 6479 the MatGetSubMatrix() routine will create the newmat for you. Any additional calls 6480 to this routine with a mat of the same nonzero structure and with a call of MAT_REUSE_MATRIX 6481 will reuse the matrix generated the first time. You should call MatDestroy() on newmat when 6482 you are finished using it. 6483 6484 The communicator of the newly obtained matrix is ALWAYS the same as the communicator of 6485 the input matrix. 6486 6487 If iscol is PETSC_NULL then all columns are obtained (not supported in Fortran). 6488 6489 Example usage: 6490 Consider the following 8x8 matrix with 34 non-zero values, that is 6491 assembled across 3 processors. Lets assume that proc0 owns 3 rows, 6492 proc1 owns 3 rows, proc2 owns 2 rows. This division can be shown 6493 as follows: 6494 6495 .vb 6496 1 2 0 | 0 3 0 | 0 4 6497 Proc0 0 5 6 | 7 0 0 | 8 0 6498 9 0 10 | 11 0 0 | 12 0 6499 ------------------------------------- 6500 13 0 14 | 15 16 17 | 0 0 6501 Proc1 0 18 0 | 19 20 21 | 0 0 6502 0 0 0 | 22 23 0 | 24 0 6503 ------------------------------------- 6504 Proc2 25 26 27 | 0 0 28 | 29 0 6505 30 0 0 | 31 32 33 | 0 34 6506 .ve 6507 6508 Suppose isrow = [0 1 | 4 | 6 7] and iscol = [1 2 | 3 4 5 | 6]. The resulting submatrix is 6509 6510 .vb 6511 2 0 | 0 3 0 | 0 6512 Proc0 5 6 | 7 0 0 | 8 6513 ------------------------------- 6514 Proc1 18 0 | 19 20 21 | 0 6515 ------------------------------- 6516 Proc2 26 27 | 0 0 28 | 29 6517 0 0 | 31 32 33 | 0 6518 .ve 6519 6520 6521 Concepts: matrices^submatrices 6522 6523 .seealso: MatGetSubMatrices() 6524 @*/ 6525 PetscErrorCode PETSCMAT_DLLEXPORT MatGetSubMatrix(Mat mat,IS isrow,IS iscol,MatReuse cll,Mat *newmat) 6526 { 6527 PetscErrorCode ierr; 6528 PetscMPIInt size; 6529 Mat *local; 6530 IS iscoltmp; 6531 6532 PetscFunctionBegin; 6533 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6534 PetscValidHeaderSpecific(isrow,IS_CLASSID,2); 6535 if (iscol) PetscValidHeaderSpecific(iscol,IS_CLASSID,3); 6536 PetscValidPointer(newmat,5); 6537 if (cll == MAT_REUSE_MATRIX) PetscValidHeaderSpecific(*newmat,MAT_CLASSID,5); 6538 PetscValidType(mat,1); 6539 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6540 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6541 ierr = MPI_Comm_size(((PetscObject)mat)->comm,&size);CHKERRQ(ierr); 6542 6543 if (!iscol) { 6544 ierr = ISCreateStride(((PetscObject)mat)->comm,mat->cmap->n,mat->cmap->rstart,1,&iscoltmp);CHKERRQ(ierr); 6545 } else { 6546 iscoltmp = iscol; 6547 } 6548 6549 /* if original matrix is on just one processor then use submatrix generated */ 6550 if (mat->ops->getsubmatrices && !mat->ops->getsubmatrix && size == 1 && cll == MAT_REUSE_MATRIX) { 6551 ierr = MatGetSubMatrices(mat,1,&isrow,&iscoltmp,MAT_REUSE_MATRIX,&newmat);CHKERRQ(ierr); 6552 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6553 PetscFunctionReturn(0); 6554 } else if (mat->ops->getsubmatrices && !mat->ops->getsubmatrix && size == 1) { 6555 ierr = MatGetSubMatrices(mat,1,&isrow,&iscoltmp,MAT_INITIAL_MATRIX,&local);CHKERRQ(ierr); 6556 *newmat = *local; 6557 ierr = PetscFree(local);CHKERRQ(ierr); 6558 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6559 PetscFunctionReturn(0); 6560 } else if (!mat->ops->getsubmatrix) { 6561 /* Create a new matrix type that implements the operation using the full matrix */ 6562 switch (cll) { 6563 case MAT_INITIAL_MATRIX: 6564 ierr = MatCreateSubMatrix(mat,isrow,iscoltmp,newmat);CHKERRQ(ierr); 6565 break; 6566 case MAT_REUSE_MATRIX: 6567 ierr = MatSubMatrixUpdate(*newmat,mat,isrow,iscoltmp);CHKERRQ(ierr); 6568 break; 6569 default: SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Invalid MatReuse, must be either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX"); 6570 } 6571 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6572 PetscFunctionReturn(0); 6573 } 6574 6575 if (!mat->ops->getsubmatrix) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6576 ierr = (*mat->ops->getsubmatrix)(mat,isrow,iscoltmp,cll,newmat);CHKERRQ(ierr); 6577 if (!iscol) {ierr = ISDestroy(iscoltmp);CHKERRQ(ierr);} 6578 ierr = PetscObjectStateIncrease((PetscObject)*newmat);CHKERRQ(ierr); 6579 PetscFunctionReturn(0); 6580 } 6581 6582 #undef __FUNCT__ 6583 #define __FUNCT__ "MatStashSetInitialSize" 6584 /*@ 6585 MatStashSetInitialSize - sets the sizes of the matrix stash, that is 6586 used during the assembly process to store values that belong to 6587 other processors. 6588 6589 Not Collective 6590 6591 Input Parameters: 6592 + mat - the matrix 6593 . size - the initial size of the stash. 6594 - bsize - the initial size of the block-stash(if used). 6595 6596 Options Database Keys: 6597 + -matstash_initial_size <size> or <size0,size1,...sizep-1> 6598 - -matstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1> 6599 6600 Level: intermediate 6601 6602 Notes: 6603 The block-stash is used for values set with MatSetValuesBlocked() while 6604 the stash is used for values set with MatSetValues() 6605 6606 Run with the option -info and look for output of the form 6607 MatAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs. 6608 to determine the appropriate value, MM, to use for size and 6609 MatAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs. 6610 to determine the value, BMM to use for bsize 6611 6612 Concepts: stash^setting matrix size 6613 Concepts: matrices^stash 6614 6615 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashGetInfo() 6616 6617 @*/ 6618 PetscErrorCode PETSCMAT_DLLEXPORT MatStashSetInitialSize(Mat mat,PetscInt size, PetscInt bsize) 6619 { 6620 PetscErrorCode ierr; 6621 6622 PetscFunctionBegin; 6623 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6624 PetscValidType(mat,1); 6625 ierr = MatStashSetInitialSize_Private(&mat->stash,size);CHKERRQ(ierr); 6626 ierr = MatStashSetInitialSize_Private(&mat->bstash,bsize);CHKERRQ(ierr); 6627 PetscFunctionReturn(0); 6628 } 6629 6630 #undef __FUNCT__ 6631 #define __FUNCT__ "MatInterpolateAdd" 6632 /*@ 6633 MatInterpolateAdd - w = y + A*x or A'*x depending on the shape of 6634 the matrix 6635 6636 Collective on Mat 6637 6638 Input Parameters: 6639 + mat - the matrix 6640 . x,y - the vectors 6641 - w - where the result is stored 6642 6643 Level: intermediate 6644 6645 Notes: 6646 w may be the same vector as y. 6647 6648 This allows one to use either the restriction or interpolation (its transpose) 6649 matrix to do the interpolation 6650 6651 Concepts: interpolation 6652 6653 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 6654 6655 @*/ 6656 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolateAdd(Mat A,Vec x,Vec y,Vec w) 6657 { 6658 PetscErrorCode ierr; 6659 PetscInt M,N; 6660 6661 PetscFunctionBegin; 6662 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6663 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6664 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6665 PetscValidHeaderSpecific(w,VEC_CLASSID,4); 6666 PetscValidType(A,1); 6667 ierr = MatPreallocated(A);CHKERRQ(ierr); 6668 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6669 if (N > M) { 6670 ierr = MatMultTransposeAdd(A,x,y,w);CHKERRQ(ierr); 6671 } else { 6672 ierr = MatMultAdd(A,x,y,w);CHKERRQ(ierr); 6673 } 6674 PetscFunctionReturn(0); 6675 } 6676 6677 #undef __FUNCT__ 6678 #define __FUNCT__ "MatInterpolate" 6679 /*@ 6680 MatInterpolate - y = A*x or A'*x depending on the shape of 6681 the matrix 6682 6683 Collective on Mat 6684 6685 Input Parameters: 6686 + mat - the matrix 6687 - x,y - the vectors 6688 6689 Level: intermediate 6690 6691 Notes: 6692 This allows one to use either the restriction or interpolation (its transpose) 6693 matrix to do the interpolation 6694 6695 Concepts: matrices^interpolation 6696 6697 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatRestrict() 6698 6699 @*/ 6700 PetscErrorCode PETSCMAT_DLLEXPORT MatInterpolate(Mat A,Vec x,Vec y) 6701 { 6702 PetscErrorCode ierr; 6703 PetscInt M,N; 6704 6705 PetscFunctionBegin; 6706 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6707 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6708 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6709 PetscValidType(A,1); 6710 ierr = MatPreallocated(A);CHKERRQ(ierr); 6711 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6712 if (N > M) { 6713 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 6714 } else { 6715 ierr = MatMult(A,x,y);CHKERRQ(ierr); 6716 } 6717 PetscFunctionReturn(0); 6718 } 6719 6720 #undef __FUNCT__ 6721 #define __FUNCT__ "MatRestrict" 6722 /*@ 6723 MatRestrict - y = A*x or A'*x 6724 6725 Collective on Mat 6726 6727 Input Parameters: 6728 + mat - the matrix 6729 - x,y - the vectors 6730 6731 Level: intermediate 6732 6733 Notes: 6734 This allows one to use either the restriction or interpolation (its transpose) 6735 matrix to do the restriction 6736 6737 Concepts: matrices^restriction 6738 6739 .seealso: MatMultAdd(), MatMultTransposeAdd(), MatInterpolate() 6740 6741 @*/ 6742 PetscErrorCode PETSCMAT_DLLEXPORT MatRestrict(Mat A,Vec x,Vec y) 6743 { 6744 PetscErrorCode ierr; 6745 PetscInt M,N; 6746 6747 PetscFunctionBegin; 6748 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 6749 PetscValidHeaderSpecific(x,VEC_CLASSID,2); 6750 PetscValidHeaderSpecific(y,VEC_CLASSID,3); 6751 PetscValidType(A,1); 6752 ierr = MatPreallocated(A);CHKERRQ(ierr); 6753 6754 ierr = MatGetSize(A,&M,&N);CHKERRQ(ierr); 6755 if (N > M) { 6756 ierr = MatMult(A,x,y);CHKERRQ(ierr); 6757 } else { 6758 ierr = MatMultTranspose(A,x,y);CHKERRQ(ierr); 6759 } 6760 PetscFunctionReturn(0); 6761 } 6762 6763 #undef __FUNCT__ 6764 #define __FUNCT__ "MatNullSpaceAttach" 6765 /*@ 6766 MatNullSpaceAttach - attaches a null space to a matrix. 6767 This null space will be removed from the resulting vector whenever 6768 MatMult() is called 6769 6770 Collective on Mat 6771 6772 Input Parameters: 6773 + mat - the matrix 6774 - nullsp - the null space object 6775 6776 Level: developer 6777 6778 Notes: 6779 Overwrites any previous null space that may have been attached 6780 6781 Concepts: null space^attaching to matrix 6782 6783 .seealso: MatCreate(), MatNullSpaceCreate() 6784 @*/ 6785 PetscErrorCode PETSCMAT_DLLEXPORT MatNullSpaceAttach(Mat mat,MatNullSpace nullsp) 6786 { 6787 PetscErrorCode ierr; 6788 6789 PetscFunctionBegin; 6790 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6791 PetscValidType(mat,1); 6792 PetscValidHeaderSpecific(nullsp,MAT_NULLSPACE_CLASSID,2); 6793 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6794 ierr = PetscObjectReference((PetscObject)nullsp);CHKERRQ(ierr); 6795 if (mat->nullsp) { ierr = MatNullSpaceDestroy(mat->nullsp);CHKERRQ(ierr); } 6796 mat->nullsp = nullsp; 6797 PetscFunctionReturn(0); 6798 } 6799 6800 #undef __FUNCT__ 6801 #define __FUNCT__ "MatICCFactor" 6802 /*@C 6803 MatICCFactor - Performs in-place incomplete Cholesky factorization of matrix. 6804 6805 Collective on Mat 6806 6807 Input Parameters: 6808 + mat - the matrix 6809 . row - row/column permutation 6810 . fill - expected fill factor >= 1.0 6811 - level - level of fill, for ICC(k) 6812 6813 Notes: 6814 Probably really in-place only when level of fill is zero, otherwise allocates 6815 new space to store factored matrix and deletes previous memory. 6816 6817 Most users should employ the simplified KSP interface for linear solvers 6818 instead of working directly with matrix algebra routines such as this. 6819 See, e.g., KSPCreate(). 6820 6821 Level: developer 6822 6823 Concepts: matrices^incomplete Cholesky factorization 6824 Concepts: Cholesky factorization 6825 6826 .seealso: MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactor() 6827 6828 Developer Note: fortran interface is not autogenerated as the f90 6829 interface defintion cannot be generated correctly [due to MatFactorInfo] 6830 6831 @*/ 6832 PetscErrorCode PETSCMAT_DLLEXPORT MatICCFactor(Mat mat,IS row,const MatFactorInfo* info) 6833 { 6834 PetscErrorCode ierr; 6835 6836 PetscFunctionBegin; 6837 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6838 PetscValidType(mat,1); 6839 if (row) PetscValidHeaderSpecific(row,IS_CLASSID,2); 6840 PetscValidPointer(info,3); 6841 if (mat->rmap->N != mat->cmap->N) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONG,"matrix must be square"); 6842 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 6843 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 6844 if (!mat->ops->iccfactor) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6845 ierr = MatPreallocated(mat);CHKERRQ(ierr); 6846 ierr = (*mat->ops->iccfactor)(mat,row,info);CHKERRQ(ierr); 6847 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6848 PetscFunctionReturn(0); 6849 } 6850 6851 #undef __FUNCT__ 6852 #define __FUNCT__ "MatSetValuesAdic" 6853 /*@ 6854 MatSetValuesAdic - Sets values computed with ADIC automatic differentiation into a matrix. 6855 6856 Not Collective 6857 6858 Input Parameters: 6859 + mat - the matrix 6860 - v - the values compute with ADIC 6861 6862 Level: developer 6863 6864 Notes: 6865 Must call MatSetColoring() before using this routine. Also this matrix must already 6866 have its nonzero pattern determined. 6867 6868 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6869 MatSetValues(), MatSetColoring(), MatSetValuesAdifor() 6870 @*/ 6871 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdic(Mat mat,void *v) 6872 { 6873 PetscErrorCode ierr; 6874 6875 PetscFunctionBegin; 6876 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6877 PetscValidType(mat,1); 6878 PetscValidPointer(mat,2); 6879 6880 if (!mat->assembled) { 6881 SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6882 } 6883 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6884 if (!mat->ops->setvaluesadic) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6885 ierr = (*mat->ops->setvaluesadic)(mat,v);CHKERRQ(ierr); 6886 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6887 ierr = MatView_Private(mat);CHKERRQ(ierr); 6888 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6889 PetscFunctionReturn(0); 6890 } 6891 6892 6893 #undef __FUNCT__ 6894 #define __FUNCT__ "MatSetColoring" 6895 /*@ 6896 MatSetColoring - Sets a coloring used by calls to MatSetValuesAdic() 6897 6898 Not Collective 6899 6900 Input Parameters: 6901 + mat - the matrix 6902 - coloring - the coloring 6903 6904 Level: developer 6905 6906 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6907 MatSetValues(), MatSetValuesAdic() 6908 @*/ 6909 PetscErrorCode PETSCMAT_DLLEXPORT MatSetColoring(Mat mat,ISColoring coloring) 6910 { 6911 PetscErrorCode ierr; 6912 6913 PetscFunctionBegin; 6914 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6915 PetscValidType(mat,1); 6916 PetscValidPointer(coloring,2); 6917 6918 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6919 if (!mat->ops->setcoloring) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6920 ierr = (*mat->ops->setcoloring)(mat,coloring);CHKERRQ(ierr); 6921 PetscFunctionReturn(0); 6922 } 6923 6924 #undef __FUNCT__ 6925 #define __FUNCT__ "MatSetValuesAdifor" 6926 /*@ 6927 MatSetValuesAdifor - Sets values computed with automatic differentiation into a matrix. 6928 6929 Not Collective 6930 6931 Input Parameters: 6932 + mat - the matrix 6933 . nl - leading dimension of v 6934 - v - the values compute with ADIFOR 6935 6936 Level: developer 6937 6938 Notes: 6939 Must call MatSetColoring() before using this routine. Also this matrix must already 6940 have its nonzero pattern determined. 6941 6942 .seealso: MatSetOption(), MatAssemblyBegin(), MatAssemblyEnd(), MatSetValuesBlocked(), MatSetValuesLocal(), 6943 MatSetValues(), MatSetColoring() 6944 @*/ 6945 PetscErrorCode PETSCMAT_DLLEXPORT MatSetValuesAdifor(Mat mat,PetscInt nl,void *v) 6946 { 6947 PetscErrorCode ierr; 6948 6949 PetscFunctionBegin; 6950 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6951 PetscValidType(mat,1); 6952 PetscValidPointer(v,3); 6953 6954 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6955 ierr = PetscLogEventBegin(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6956 if (!mat->ops->setvaluesadifor) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 6957 ierr = (*mat->ops->setvaluesadifor)(mat,nl,v);CHKERRQ(ierr); 6958 ierr = PetscLogEventEnd(MAT_SetValues,mat,0,0,0);CHKERRQ(ierr); 6959 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 6960 PetscFunctionReturn(0); 6961 } 6962 6963 #undef __FUNCT__ 6964 #define __FUNCT__ "MatDiagonalScaleLocal" 6965 /*@ 6966 MatDiagonalScaleLocal - Scales columns of a matrix given the scaling values including the 6967 ghosted ones. 6968 6969 Not Collective 6970 6971 Input Parameters: 6972 + mat - the matrix 6973 - diag = the diagonal values, including ghost ones 6974 6975 Level: developer 6976 6977 Notes: Works only for MPIAIJ and MPIBAIJ matrices 6978 6979 .seealso: MatDiagonalScale() 6980 @*/ 6981 PetscErrorCode PETSCMAT_DLLEXPORT MatDiagonalScaleLocal(Mat mat,Vec diag) 6982 { 6983 PetscErrorCode ierr; 6984 PetscMPIInt size; 6985 6986 PetscFunctionBegin; 6987 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 6988 PetscValidHeaderSpecific(diag,VEC_CLASSID,2); 6989 PetscValidType(mat,1); 6990 6991 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Matrix must be already assembled"); 6992 ierr = PetscLogEventBegin(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 6993 ierr = MPI_Comm_size(((PetscObject)mat)->comm,&size);CHKERRQ(ierr); 6994 if (size == 1) { 6995 PetscInt n,m; 6996 ierr = VecGetSize(diag,&n);CHKERRQ(ierr); 6997 ierr = MatGetSize(mat,0,&m);CHKERRQ(ierr); 6998 if (m == n) { 6999 ierr = MatDiagonalScale(mat,0,diag);CHKERRQ(ierr); 7000 } else { 7001 SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Only supported for sequential matrices when no ghost points/periodic conditions"); 7002 } 7003 } else { 7004 PetscErrorCode (*f)(Mat,Vec); 7005 ierr = PetscObjectQueryFunction((PetscObject)mat,"MatDiagonalScaleLocal_C",(void (**)(void))&f);CHKERRQ(ierr); 7006 if (f) { 7007 ierr = (*f)(mat,diag);CHKERRQ(ierr); 7008 } else { 7009 SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Only supported for MPIAIJ and MPIBAIJ parallel matrices"); 7010 } 7011 } 7012 ierr = PetscLogEventEnd(MAT_Scale,mat,0,0,0);CHKERRQ(ierr); 7013 ierr = PetscObjectStateIncrease((PetscObject)mat);CHKERRQ(ierr); 7014 PetscFunctionReturn(0); 7015 } 7016 7017 #undef __FUNCT__ 7018 #define __FUNCT__ "MatGetInertia" 7019 /*@ 7020 MatGetInertia - Gets the inertia from a factored matrix 7021 7022 Collective on Mat 7023 7024 Input Parameter: 7025 . mat - the matrix 7026 7027 Output Parameters: 7028 + nneg - number of negative eigenvalues 7029 . nzero - number of zero eigenvalues 7030 - npos - number of positive eigenvalues 7031 7032 Level: advanced 7033 7034 Notes: Matrix must have been factored by MatCholeskyFactor() 7035 7036 7037 @*/ 7038 PetscErrorCode PETSCMAT_DLLEXPORT MatGetInertia(Mat mat,PetscInt *nneg,PetscInt *nzero,PetscInt *npos) 7039 { 7040 PetscErrorCode ierr; 7041 7042 PetscFunctionBegin; 7043 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7044 PetscValidType(mat,1); 7045 if (!mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 7046 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Numeric factor mat is not assembled"); 7047 if (!mat->ops->getinertia) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 7048 ierr = (*mat->ops->getinertia)(mat,nneg,nzero,npos);CHKERRQ(ierr); 7049 PetscFunctionReturn(0); 7050 } 7051 7052 /* ----------------------------------------------------------------*/ 7053 #undef __FUNCT__ 7054 #define __FUNCT__ "MatSolves" 7055 /*@C 7056 MatSolves - Solves A x = b, given a factored matrix, for a collection of vectors 7057 7058 Collective on Mat and Vecs 7059 7060 Input Parameters: 7061 + mat - the factored matrix 7062 - b - the right-hand-side vectors 7063 7064 Output Parameter: 7065 . x - the result vectors 7066 7067 Notes: 7068 The vectors b and x cannot be the same. I.e., one cannot 7069 call MatSolves(A,x,x). 7070 7071 Notes: 7072 Most users should employ the simplified KSP interface for linear solvers 7073 instead of working directly with matrix algebra routines such as this. 7074 See, e.g., KSPCreate(). 7075 7076 Level: developer 7077 7078 Concepts: matrices^triangular solves 7079 7080 .seealso: MatSolveAdd(), MatSolveTranspose(), MatSolveTransposeAdd(), MatSolve() 7081 @*/ 7082 PetscErrorCode PETSCMAT_DLLEXPORT MatSolves(Mat mat,Vecs b,Vecs x) 7083 { 7084 PetscErrorCode ierr; 7085 7086 PetscFunctionBegin; 7087 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7088 PetscValidType(mat,1); 7089 if (x == b) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_IDN,"x and b must be different vectors"); 7090 if (!mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Unfactored matrix"); 7091 if (!mat->rmap->N && !mat->cmap->N) PetscFunctionReturn(0); 7092 7093 if (!mat->ops->solves) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 7094 ierr = MatPreallocated(mat);CHKERRQ(ierr); 7095 ierr = PetscLogEventBegin(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 7096 ierr = (*mat->ops->solves)(mat,b,x);CHKERRQ(ierr); 7097 ierr = PetscLogEventEnd(MAT_Solves,mat,0,0,0);CHKERRQ(ierr); 7098 PetscFunctionReturn(0); 7099 } 7100 7101 #undef __FUNCT__ 7102 #define __FUNCT__ "MatIsSymmetric" 7103 /*@ 7104 MatIsSymmetric - Test whether a matrix is symmetric 7105 7106 Collective on Mat 7107 7108 Input Parameter: 7109 + A - the matrix to test 7110 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact transpose) 7111 7112 Output Parameters: 7113 . flg - the result 7114 7115 Level: intermediate 7116 7117 Concepts: matrix^symmetry 7118 7119 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 7120 @*/ 7121 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetric(Mat A,PetscReal tol,PetscTruth *flg) 7122 { 7123 PetscErrorCode ierr; 7124 7125 PetscFunctionBegin; 7126 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7127 PetscValidPointer(flg,2); 7128 7129 if (!A->symmetric_set) { 7130 if (!A->ops->issymmetric) { 7131 const MatType mattype; 7132 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7133 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 7134 } 7135 ierr = (*A->ops->issymmetric)(A,tol,flg);CHKERRQ(ierr); 7136 if (!tol) { 7137 A->symmetric_set = PETSC_TRUE; 7138 A->symmetric = *flg; 7139 if (A->symmetric) { 7140 A->structurally_symmetric_set = PETSC_TRUE; 7141 A->structurally_symmetric = PETSC_TRUE; 7142 } 7143 } 7144 } else if (A->symmetric) { 7145 *flg = PETSC_TRUE; 7146 } else if (!tol) { 7147 *flg = PETSC_FALSE; 7148 } else { 7149 if (!A->ops->issymmetric) { 7150 const MatType mattype; 7151 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7152 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for symmetric",mattype); 7153 } 7154 ierr = (*A->ops->issymmetric)(A,tol,flg);CHKERRQ(ierr); 7155 } 7156 PetscFunctionReturn(0); 7157 } 7158 7159 #undef __FUNCT__ 7160 #define __FUNCT__ "MatIsHermitian" 7161 /*@ 7162 MatIsHermitian - Test whether a matrix is Hermitian 7163 7164 Collective on Mat 7165 7166 Input Parameter: 7167 + A - the matrix to test 7168 - tol - difference between value and its transpose less than this amount counts as equal (use 0.0 for exact Hermitian) 7169 7170 Output Parameters: 7171 . flg - the result 7172 7173 Level: intermediate 7174 7175 Concepts: matrix^symmetry 7176 7177 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetricKnown() 7178 @*/ 7179 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitian(Mat A,PetscReal tol,PetscTruth *flg) 7180 { 7181 PetscErrorCode ierr; 7182 7183 PetscFunctionBegin; 7184 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7185 PetscValidPointer(flg,2); 7186 7187 if (!A->hermitian_set) { 7188 if (!A->ops->ishermitian) { 7189 const MatType mattype; 7190 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7191 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for hermitian",mattype); 7192 } 7193 ierr = (*A->ops->ishermitian)(A,tol,flg);CHKERRQ(ierr); 7194 if (!tol) { 7195 A->hermitian_set = PETSC_TRUE; 7196 A->hermitian = *flg; 7197 if (A->hermitian) { 7198 A->structurally_symmetric_set = PETSC_TRUE; 7199 A->structurally_symmetric = PETSC_TRUE; 7200 } 7201 } 7202 } else if (A->hermitian) { 7203 *flg = PETSC_TRUE; 7204 } else if (!tol) { 7205 *flg = PETSC_FALSE; 7206 } else { 7207 if (!A->ops->ishermitian) { 7208 const MatType mattype; 7209 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7210 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Matrix of type <%s> does not support checking for hermitian",mattype); 7211 } 7212 ierr = (*A->ops->ishermitian)(A,tol,flg);CHKERRQ(ierr); 7213 } 7214 PetscFunctionReturn(0); 7215 } 7216 7217 #undef __FUNCT__ 7218 #define __FUNCT__ "MatIsSymmetricKnown" 7219 /*@ 7220 MatIsSymmetricKnown - Checks the flag on the matrix to see if it is symmetric. 7221 7222 Collective on Mat 7223 7224 Input Parameter: 7225 . A - the matrix to check 7226 7227 Output Parameters: 7228 + set - if the symmetric flag is set (this tells you if the next flag is valid) 7229 - flg - the result 7230 7231 Level: advanced 7232 7233 Concepts: matrix^symmetry 7234 7235 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsSymmetric() 7236 if you want it explicitly checked 7237 7238 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 7239 @*/ 7240 PetscErrorCode PETSCMAT_DLLEXPORT MatIsSymmetricKnown(Mat A,PetscTruth *set,PetscTruth *flg) 7241 { 7242 PetscFunctionBegin; 7243 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7244 PetscValidPointer(set,2); 7245 PetscValidPointer(flg,3); 7246 if (A->symmetric_set) { 7247 *set = PETSC_TRUE; 7248 *flg = A->symmetric; 7249 } else { 7250 *set = PETSC_FALSE; 7251 } 7252 PetscFunctionReturn(0); 7253 } 7254 7255 #undef __FUNCT__ 7256 #define __FUNCT__ "MatIsHermitianKnown" 7257 /*@ 7258 MatIsHermitianKnown - Checks the flag on the matrix to see if it is hermitian. 7259 7260 Collective on Mat 7261 7262 Input Parameter: 7263 . A - the matrix to check 7264 7265 Output Parameters: 7266 + set - if the hermitian flag is set (this tells you if the next flag is valid) 7267 - flg - the result 7268 7269 Level: advanced 7270 7271 Concepts: matrix^symmetry 7272 7273 Note: Does not check the matrix values directly, so this may return unknown (set = PETSC_FALSE). Use MatIsHermitian() 7274 if you want it explicitly checked 7275 7276 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsStructurallySymmetric(), MatSetOption(), MatIsSymmetric() 7277 @*/ 7278 PetscErrorCode PETSCMAT_DLLEXPORT MatIsHermitianKnown(Mat A,PetscTruth *set,PetscTruth *flg) 7279 { 7280 PetscFunctionBegin; 7281 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7282 PetscValidPointer(set,2); 7283 PetscValidPointer(flg,3); 7284 if (A->hermitian_set) { 7285 *set = PETSC_TRUE; 7286 *flg = A->hermitian; 7287 } else { 7288 *set = PETSC_FALSE; 7289 } 7290 PetscFunctionReturn(0); 7291 } 7292 7293 #undef __FUNCT__ 7294 #define __FUNCT__ "MatIsStructurallySymmetric" 7295 /*@ 7296 MatIsStructurallySymmetric - Test whether a matrix is structurally symmetric 7297 7298 Collective on Mat 7299 7300 Input Parameter: 7301 . A - the matrix to test 7302 7303 Output Parameters: 7304 . flg - the result 7305 7306 Level: intermediate 7307 7308 Concepts: matrix^symmetry 7309 7310 .seealso: MatTranspose(), MatIsTranspose(), MatIsHermitian(), MatIsSymmetric(), MatSetOption() 7311 @*/ 7312 PetscErrorCode PETSCMAT_DLLEXPORT MatIsStructurallySymmetric(Mat A,PetscTruth *flg) 7313 { 7314 PetscErrorCode ierr; 7315 7316 PetscFunctionBegin; 7317 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7318 PetscValidPointer(flg,2); 7319 if (!A->structurally_symmetric_set) { 7320 if (!A->ops->isstructurallysymmetric) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_SUP,"Matrix does not support checking for structural symmetric"); 7321 ierr = (*A->ops->isstructurallysymmetric)(A,&A->structurally_symmetric);CHKERRQ(ierr); 7322 A->structurally_symmetric_set = PETSC_TRUE; 7323 } 7324 *flg = A->structurally_symmetric; 7325 PetscFunctionReturn(0); 7326 } 7327 7328 #undef __FUNCT__ 7329 #define __FUNCT__ "MatStashGetInfo" 7330 extern PetscErrorCode MatStashGetInfo_Private(MatStash*,PetscInt*,PetscInt*); 7331 /*@ 7332 MatStashGetInfo - Gets how many values are currently in the vector stash, i.e. need 7333 to be communicated to other processors during the MatAssemblyBegin/End() process 7334 7335 Not collective 7336 7337 Input Parameter: 7338 . vec - the vector 7339 7340 Output Parameters: 7341 + nstash - the size of the stash 7342 . reallocs - the number of additional mallocs incurred. 7343 . bnstash - the size of the block stash 7344 - breallocs - the number of additional mallocs incurred.in the block stash 7345 7346 Level: advanced 7347 7348 .seealso: MatAssemblyBegin(), MatAssemblyEnd(), Mat, MatStashSetInitialSize() 7349 7350 @*/ 7351 PetscErrorCode PETSCMAT_DLLEXPORT MatStashGetInfo(Mat mat,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs) 7352 { 7353 PetscErrorCode ierr; 7354 PetscFunctionBegin; 7355 ierr = MatStashGetInfo_Private(&mat->stash,nstash,reallocs);CHKERRQ(ierr); 7356 ierr = MatStashGetInfo_Private(&mat->bstash,bnstash,breallocs);CHKERRQ(ierr); 7357 PetscFunctionReturn(0); 7358 } 7359 7360 #undef __FUNCT__ 7361 #define __FUNCT__ "MatGetVecs" 7362 /*@C 7363 MatGetVecs - Get vector(s) compatible with the matrix, i.e. with the same 7364 parallel layout 7365 7366 Collective on Mat 7367 7368 Input Parameter: 7369 . mat - the matrix 7370 7371 Output Parameter: 7372 + right - (optional) vector that the matrix can be multiplied against 7373 - left - (optional) vector that the matrix vector product can be stored in 7374 7375 Level: advanced 7376 7377 .seealso: MatCreate() 7378 @*/ 7379 PetscErrorCode PETSCMAT_DLLEXPORT MatGetVecs(Mat mat,Vec *right,Vec *left) 7380 { 7381 PetscErrorCode ierr; 7382 7383 PetscFunctionBegin; 7384 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7385 PetscValidType(mat,1); 7386 ierr = MatPreallocated(mat);CHKERRQ(ierr); 7387 if (mat->ops->getvecs) { 7388 ierr = (*mat->ops->getvecs)(mat,right,left);CHKERRQ(ierr); 7389 } else { 7390 PetscMPIInt size; 7391 ierr = MPI_Comm_size(((PetscObject)mat)->comm, &size);CHKERRQ(ierr); 7392 if (right) { 7393 ierr = VecCreate(((PetscObject)mat)->comm,right);CHKERRQ(ierr); 7394 ierr = VecSetSizes(*right,mat->cmap->n,PETSC_DETERMINE);CHKERRQ(ierr); 7395 ierr = VecSetBlockSize(*right,mat->rmap->bs);CHKERRQ(ierr); 7396 if (size > 1) { 7397 /* New vectors uses Mat cmap and does not create a new one */ 7398 ierr = PetscLayoutDestroy((*right)->map);CHKERRQ(ierr); 7399 (*right)->map = mat->cmap; 7400 mat->cmap->refcnt++; 7401 7402 ierr = VecSetType(*right,VECMPI);CHKERRQ(ierr); 7403 } else {ierr = VecSetType(*right,VECSEQ);CHKERRQ(ierr);} 7404 } 7405 if (left) { 7406 ierr = VecCreate(((PetscObject)mat)->comm,left);CHKERRQ(ierr); 7407 ierr = VecSetSizes(*left,mat->rmap->n,PETSC_DETERMINE);CHKERRQ(ierr); 7408 ierr = VecSetBlockSize(*left,mat->rmap->bs);CHKERRQ(ierr); 7409 if (size > 1) { 7410 /* New vectors uses Mat rmap and does not create a new one */ 7411 ierr = PetscLayoutDestroy((*left)->map);CHKERRQ(ierr); 7412 (*left)->map = mat->rmap; 7413 mat->rmap->refcnt++; 7414 7415 ierr = VecSetType(*left,VECMPI);CHKERRQ(ierr); 7416 } else {ierr = VecSetType(*left,VECSEQ);CHKERRQ(ierr);} 7417 } 7418 } 7419 if (mat->mapping) { 7420 if (right) {ierr = VecSetLocalToGlobalMapping(*right,mat->mapping);CHKERRQ(ierr);} 7421 if (left) {ierr = VecSetLocalToGlobalMapping(*left,mat->mapping);CHKERRQ(ierr);} 7422 } 7423 if (mat->bmapping) { 7424 if (right) {ierr = VecSetLocalToGlobalMappingBlock(*right,mat->bmapping);CHKERRQ(ierr);} 7425 if (left) {ierr = VecSetLocalToGlobalMappingBlock(*left,mat->bmapping);CHKERRQ(ierr);} 7426 } 7427 PetscFunctionReturn(0); 7428 } 7429 7430 #undef __FUNCT__ 7431 #define __FUNCT__ "MatFactorInfoInitialize" 7432 /*@C 7433 MatFactorInfoInitialize - Initializes a MatFactorInfo data structure 7434 with default values. 7435 7436 Not Collective 7437 7438 Input Parameters: 7439 . info - the MatFactorInfo data structure 7440 7441 7442 Notes: The solvers are generally used through the KSP and PC objects, for example 7443 PCLU, PCILU, PCCHOLESKY, PCICC 7444 7445 Level: developer 7446 7447 .seealso: MatFactorInfo 7448 7449 Developer Note: fortran interface is not autogenerated as the f90 7450 interface defintion cannot be generated correctly [due to MatFactorInfo] 7451 7452 @*/ 7453 7454 PetscErrorCode PETSCMAT_DLLEXPORT MatFactorInfoInitialize(MatFactorInfo *info) 7455 { 7456 PetscErrorCode ierr; 7457 7458 PetscFunctionBegin; 7459 ierr = PetscMemzero(info,sizeof(MatFactorInfo));CHKERRQ(ierr); 7460 PetscFunctionReturn(0); 7461 } 7462 7463 #undef __FUNCT__ 7464 #define __FUNCT__ "MatPtAP" 7465 /*@ 7466 MatPtAP - Creates the matrix projection C = P^T * A * P 7467 7468 Collective on Mat 7469 7470 Input Parameters: 7471 + A - the matrix 7472 . P - the projection matrix 7473 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7474 - fill - expected fill as ratio of nnz(C)/nnz(A) 7475 7476 Output Parameters: 7477 . C - the product matrix 7478 7479 Notes: 7480 C will be created and must be destroyed by the user with MatDestroy(). 7481 7482 This routine is currently only implemented for pairs of AIJ matrices and classes 7483 which inherit from AIJ. 7484 7485 Level: intermediate 7486 7487 .seealso: MatPtAPSymbolic(), MatPtAPNumeric(), MatMatMult() 7488 @*/ 7489 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAP(Mat A,Mat P,MatReuse scall,PetscReal fill,Mat *C) 7490 { 7491 PetscErrorCode ierr; 7492 7493 PetscFunctionBegin; 7494 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7495 PetscValidType(A,1); 7496 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7497 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7498 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7499 PetscValidType(P,2); 7500 ierr = MatPreallocated(P);CHKERRQ(ierr); 7501 if (!P->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7502 if (P->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7503 PetscValidPointer(C,3); 7504 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); 7505 if (fill < 1.0) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7506 ierr = MatPreallocated(A);CHKERRQ(ierr); 7507 7508 if (!A->ops->ptap) { 7509 const MatType mattype; 7510 ierr = MatGetType(A,&mattype);CHKERRQ(ierr); 7511 SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"Matrix of type <%s> does not support PtAP",mattype); 7512 } 7513 ierr = PetscLogEventBegin(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 7514 ierr = (*A->ops->ptap)(A,P,scall,fill,C);CHKERRQ(ierr); 7515 ierr = PetscLogEventEnd(MAT_PtAP,A,P,0,0);CHKERRQ(ierr); 7516 7517 PetscFunctionReturn(0); 7518 } 7519 7520 #undef __FUNCT__ 7521 #define __FUNCT__ "MatPtAPNumeric" 7522 /*@ 7523 MatPtAPNumeric - Computes the matrix projection C = P^T * A * P 7524 7525 Collective on Mat 7526 7527 Input Parameters: 7528 + A - the matrix 7529 - P - the projection matrix 7530 7531 Output Parameters: 7532 . C - the product matrix 7533 7534 Notes: 7535 C must have been created by calling MatPtAPSymbolic and must be destroyed by 7536 the user using MatDeatroy(). 7537 7538 This routine is currently only implemented for pairs of AIJ matrices and classes 7539 which inherit from AIJ. C will be of type MATAIJ. 7540 7541 Level: intermediate 7542 7543 .seealso: MatPtAP(), MatPtAPSymbolic(), MatMatMultNumeric() 7544 @*/ 7545 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPNumeric(Mat A,Mat P,Mat C) 7546 { 7547 PetscErrorCode ierr; 7548 7549 PetscFunctionBegin; 7550 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7551 PetscValidType(A,1); 7552 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7553 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7554 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7555 PetscValidType(P,2); 7556 ierr = MatPreallocated(P);CHKERRQ(ierr); 7557 if (!P->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7558 if (P->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7559 PetscValidHeaderSpecific(C,MAT_CLASSID,3); 7560 PetscValidType(C,3); 7561 ierr = MatPreallocated(C);CHKERRQ(ierr); 7562 if (C->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7563 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); 7564 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); 7565 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); 7566 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); 7567 ierr = MatPreallocated(A);CHKERRQ(ierr); 7568 7569 ierr = PetscLogEventBegin(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 7570 ierr = (*A->ops->ptapnumeric)(A,P,C);CHKERRQ(ierr); 7571 ierr = PetscLogEventEnd(MAT_PtAPNumeric,A,P,0,0);CHKERRQ(ierr); 7572 PetscFunctionReturn(0); 7573 } 7574 7575 #undef __FUNCT__ 7576 #define __FUNCT__ "MatPtAPSymbolic" 7577 /*@ 7578 MatPtAPSymbolic - Creates the (i,j) structure of the matrix projection C = P^T * A * P 7579 7580 Collective on Mat 7581 7582 Input Parameters: 7583 + A - the matrix 7584 - P - the projection matrix 7585 7586 Output Parameters: 7587 . C - the (i,j) structure of the product matrix 7588 7589 Notes: 7590 C will be created and must be destroyed by the user with MatDestroy(). 7591 7592 This routine is currently only implemented for pairs of SeqAIJ matrices and classes 7593 which inherit from SeqAIJ. C will be of type MATSEQAIJ. The product is computed using 7594 this (i,j) structure by calling MatPtAPNumeric(). 7595 7596 Level: intermediate 7597 7598 .seealso: MatPtAP(), MatPtAPNumeric(), MatMatMultSymbolic() 7599 @*/ 7600 PetscErrorCode PETSCMAT_DLLEXPORT MatPtAPSymbolic(Mat A,Mat P,PetscReal fill,Mat *C) 7601 { 7602 PetscErrorCode ierr; 7603 7604 PetscFunctionBegin; 7605 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7606 PetscValidType(A,1); 7607 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7608 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7609 if (fill <1.0) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7610 PetscValidHeaderSpecific(P,MAT_CLASSID,2); 7611 PetscValidType(P,2); 7612 ierr = MatPreallocated(P);CHKERRQ(ierr); 7613 if (!P->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7614 if (P->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7615 PetscValidPointer(C,3); 7616 7617 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); 7618 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); 7619 ierr = MatPreallocated(A);CHKERRQ(ierr); 7620 ierr = PetscLogEventBegin(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 7621 ierr = (*A->ops->ptapsymbolic)(A,P,fill,C);CHKERRQ(ierr); 7622 ierr = PetscLogEventEnd(MAT_PtAPSymbolic,A,P,0,0);CHKERRQ(ierr); 7623 7624 ierr = MatSetBlockSize(*C,A->rmap->bs);CHKERRQ(ierr); 7625 7626 PetscFunctionReturn(0); 7627 } 7628 7629 #undef __FUNCT__ 7630 #define __FUNCT__ "MatMatMult" 7631 /*@ 7632 MatMatMult - Performs Matrix-Matrix Multiplication C=A*B. 7633 7634 Collective on Mat 7635 7636 Input Parameters: 7637 + A - the left matrix 7638 . B - the right matrix 7639 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7640 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if you do not have a good estimate 7641 if the result is a dense matrix this is irrelevent 7642 7643 Output Parameters: 7644 . C - the product matrix 7645 7646 Notes: 7647 Unless scall is MAT_REUSE_MATRIX C will be created. 7648 7649 MAT_REUSE_MATRIX can only be used if the matrices A and B have the same nonzero pattern as in the previous call 7650 7651 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7652 actually needed. 7653 7654 If you have many matrices with the same non-zero structure to multiply, you 7655 should either 7656 $ 1) use MAT_REUSE_MATRIX in all calls but the first or 7657 $ 2) call MatMatMultSymbolic() once and then MatMatMultNumeric() for each product needed 7658 7659 Level: intermediate 7660 7661 .seealso: MatMatMultSymbolic(), MatMatMultNumeric(), MatPtAP() 7662 @*/ 7663 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMult(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 7664 { 7665 PetscErrorCode ierr; 7666 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 7667 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 7668 PetscErrorCode (*mult)(Mat,Mat,MatReuse,PetscReal,Mat *)=PETSC_NULL; 7669 7670 PetscFunctionBegin; 7671 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7672 PetscValidType(A,1); 7673 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7674 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7675 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7676 PetscValidType(B,2); 7677 ierr = MatPreallocated(B);CHKERRQ(ierr); 7678 if (!B->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7679 if (B->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7680 PetscValidPointer(C,3); 7681 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); 7682 if (scall == MAT_REUSE_MATRIX){ 7683 PetscValidPointer(*C,5); 7684 PetscValidHeaderSpecific(*C,MAT_CLASSID,5); 7685 } 7686 if (fill == PETSC_DEFAULT || fill == PETSC_DECIDE) fill = 2.0; 7687 if (fill < 1.0) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_ARG_SIZ,"Expected fill=%G must be >= 1.0",fill); 7688 ierr = MatPreallocated(A);CHKERRQ(ierr); 7689 7690 fA = A->ops->matmult; 7691 fB = B->ops->matmult; 7692 if (fB == fA) { 7693 if (!fB) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"MatMatMult not supported for B of type %s",((PetscObject)B)->type_name); 7694 mult = fB; 7695 } else { 7696 /* dispatch based on the type of A and B */ 7697 char multname[256]; 7698 ierr = PetscStrcpy(multname,"MatMatMult_");CHKERRQ(ierr); 7699 ierr = PetscStrcat(multname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7700 ierr = PetscStrcat(multname,"_");CHKERRQ(ierr); 7701 ierr = PetscStrcat(multname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7702 ierr = PetscStrcat(multname,"_C");CHKERRQ(ierr); /* e.g., multname = "MatMatMult_seqdense_seqaij_C" */ 7703 ierr = PetscObjectQueryFunction((PetscObject)B,multname,(void (**)(void))&mult);CHKERRQ(ierr); 7704 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); 7705 } 7706 ierr = PetscLogEventBegin(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 7707 ierr = (*mult)(A,B,scall,fill,C);CHKERRQ(ierr); 7708 ierr = PetscLogEventEnd(MAT_MatMult,A,B,0,0);CHKERRQ(ierr); 7709 PetscFunctionReturn(0); 7710 } 7711 7712 #undef __FUNCT__ 7713 #define __FUNCT__ "MatMatMultSymbolic" 7714 /*@ 7715 MatMatMultSymbolic - Performs construction, preallocation, and computes the ij structure 7716 of the matrix-matrix product C=A*B. Call this routine before calling MatMatMultNumeric(). 7717 7718 Collective on Mat 7719 7720 Input Parameters: 7721 + A - the left matrix 7722 . B - the right matrix 7723 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if you do not have a good estimate, 7724 if C is a dense matrix this is irrelevent 7725 7726 Output Parameters: 7727 . C - the product matrix 7728 7729 Notes: 7730 Unless scall is MAT_REUSE_MATRIX C will be created. 7731 7732 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7733 actually needed. 7734 7735 This routine is currently implemented for 7736 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type AIJ 7737 - pairs of AIJ (A) and Dense (B) matrix, C will be of type Dense. 7738 - pairs of Dense (A) and AIJ (B) matrix, C will be of type Dense. 7739 7740 Level: intermediate 7741 7742 Developers Note: There are ways to estimate the number of nonzeros in the resulting product, see for example, http://arxiv.org/abs/1006.4173 7743 We should incorporate them into PETSc. 7744 7745 .seealso: MatMatMult(), MatMatMultNumeric() 7746 @*/ 7747 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultSymbolic(Mat A,Mat B,PetscReal fill,Mat *C) 7748 { 7749 PetscErrorCode ierr; 7750 PetscErrorCode (*Asymbolic)(Mat,Mat,PetscReal,Mat *); 7751 PetscErrorCode (*Bsymbolic)(Mat,Mat,PetscReal,Mat *); 7752 PetscErrorCode (*symbolic)(Mat,Mat,PetscReal,Mat *)=PETSC_NULL; 7753 7754 PetscFunctionBegin; 7755 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7756 PetscValidType(A,1); 7757 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7758 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7759 7760 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7761 PetscValidType(B,2); 7762 ierr = MatPreallocated(B);CHKERRQ(ierr); 7763 if (!B->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7764 if (B->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7765 PetscValidPointer(C,3); 7766 7767 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); 7768 if (fill == PETSC_DEFAULT) fill = 2.0; 7769 if (fill < 1.0) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 7770 ierr = MatPreallocated(A);CHKERRQ(ierr); 7771 7772 Asymbolic = A->ops->matmultsymbolic; 7773 Bsymbolic = B->ops->matmultsymbolic; 7774 if (Asymbolic == Bsymbolic){ 7775 if (!Bsymbolic) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"C=A*B not implemented for B of type %s",((PetscObject)B)->type_name); 7776 symbolic = Bsymbolic; 7777 } else { /* dispatch based on the type of A and B */ 7778 char symbolicname[256]; 7779 ierr = PetscStrcpy(symbolicname,"MatMatMultSymbolic_");CHKERRQ(ierr); 7780 ierr = PetscStrcat(symbolicname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7781 ierr = PetscStrcat(symbolicname,"_");CHKERRQ(ierr); 7782 ierr = PetscStrcat(symbolicname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7783 ierr = PetscStrcat(symbolicname,"_C");CHKERRQ(ierr); 7784 ierr = PetscObjectQueryFunction((PetscObject)B,symbolicname,(void (**)(void))&symbolic);CHKERRQ(ierr); 7785 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); 7786 } 7787 ierr = PetscLogEventBegin(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 7788 ierr = (*symbolic)(A,B,fill,C);CHKERRQ(ierr); 7789 ierr = PetscLogEventEnd(MAT_MatMultSymbolic,A,B,0,0);CHKERRQ(ierr); 7790 PetscFunctionReturn(0); 7791 } 7792 7793 #undef __FUNCT__ 7794 #define __FUNCT__ "MatMatMultNumeric" 7795 /*@ 7796 MatMatMultNumeric - Performs the numeric matrix-matrix product. 7797 Call this routine after first calling MatMatMultSymbolic(). 7798 7799 Collective on Mat 7800 7801 Input Parameters: 7802 + A - the left matrix 7803 - B - the right matrix 7804 7805 Output Parameters: 7806 . C - the product matrix, which was created by from MatMatMultSymbolic() or a call to MatMatMult(). 7807 7808 Notes: 7809 C must have been created with MatMatMultSymbolic(). 7810 7811 This routine is currently implemented for 7812 - pairs of AIJ matrices and classes which inherit from AIJ, C will be of type MATAIJ. 7813 - pairs of AIJ (A) and Dense (B) matrix, C will be of type Dense. 7814 - pairs of Dense (A) and AIJ (B) matrix, C will be of type Dense. 7815 7816 Level: intermediate 7817 7818 .seealso: MatMatMult(), MatMatMultSymbolic() 7819 @*/ 7820 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultNumeric(Mat A,Mat B,Mat C) 7821 { 7822 PetscErrorCode ierr; 7823 PetscErrorCode (*Anumeric)(Mat,Mat,Mat); 7824 PetscErrorCode (*Bnumeric)(Mat,Mat,Mat); 7825 PetscErrorCode (*numeric)(Mat,Mat,Mat)=PETSC_NULL; 7826 7827 PetscFunctionBegin; 7828 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7829 PetscValidType(A,1); 7830 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7831 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7832 7833 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7834 PetscValidType(B,2); 7835 ierr = MatPreallocated(B);CHKERRQ(ierr); 7836 if (!B->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7837 if (B->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7838 7839 PetscValidHeaderSpecific(C,MAT_CLASSID,3); 7840 PetscValidType(C,3); 7841 ierr = MatPreallocated(C);CHKERRQ(ierr); 7842 if (!C->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7843 if (C->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7844 7845 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); 7846 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); 7847 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); 7848 ierr = MatPreallocated(A);CHKERRQ(ierr); 7849 7850 Anumeric = A->ops->matmultnumeric; 7851 Bnumeric = B->ops->matmultnumeric; 7852 if (Anumeric == Bnumeric){ 7853 if (!Bnumeric) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"MatMatMultNumeric not supported for B of type %s",((PetscObject)B)->type_name); 7854 numeric = Bnumeric; 7855 } else { 7856 char numericname[256]; 7857 ierr = PetscStrcpy(numericname,"MatMatMultNumeric_");CHKERRQ(ierr); 7858 ierr = PetscStrcat(numericname,((PetscObject)A)->type_name);CHKERRQ(ierr); 7859 ierr = PetscStrcat(numericname,"_");CHKERRQ(ierr); 7860 ierr = PetscStrcat(numericname,((PetscObject)B)->type_name);CHKERRQ(ierr); 7861 ierr = PetscStrcat(numericname,"_C");CHKERRQ(ierr); 7862 ierr = PetscObjectQueryFunction((PetscObject)B,numericname,(void (**)(void))&numeric);CHKERRQ(ierr); 7863 if (!numeric) 7864 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); 7865 } 7866 ierr = PetscLogEventBegin(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 7867 ierr = (*numeric)(A,B,C);CHKERRQ(ierr); 7868 ierr = PetscLogEventEnd(MAT_MatMultNumeric,A,B,0,0);CHKERRQ(ierr); 7869 PetscFunctionReturn(0); 7870 } 7871 7872 #undef __FUNCT__ 7873 #define __FUNCT__ "MatMatMultTranspose" 7874 /*@ 7875 MatMatMultTranspose - Performs Matrix-Matrix Multiplication C=A^T*B. 7876 7877 Collective on Mat 7878 7879 Input Parameters: 7880 + A - the left matrix 7881 . B - the right matrix 7882 . scall - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7883 - fill - expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use PETSC_DEFAULT if not known 7884 7885 Output Parameters: 7886 . C - the product matrix 7887 7888 Notes: 7889 C will be created if MAT_INITIAL_MATRIX and must be destroyed by the user with MatDestroy(). 7890 7891 MAT_REUSE_MATRIX can only be used if the matrices A and B have the same nonzero pattern as in the previous call 7892 7893 To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value 7894 actually needed. 7895 7896 This routine is currently only implemented for pairs of SeqAIJ matrices and pairs of SeqDense matrices and classes 7897 which inherit from SeqAIJ. C will be of type MATSEQAIJ. 7898 7899 Level: intermediate 7900 7901 .seealso: MatMatMultTransposeSymbolic(), MatMatMultTransposeNumeric(), MatPtAP() 7902 @*/ 7903 PetscErrorCode PETSCMAT_DLLEXPORT MatMatMultTranspose(Mat A,Mat B,MatReuse scall,PetscReal fill,Mat *C) 7904 { 7905 PetscErrorCode ierr; 7906 PetscErrorCode (*fA)(Mat,Mat,MatReuse,PetscReal,Mat*); 7907 PetscErrorCode (*fB)(Mat,Mat,MatReuse,PetscReal,Mat*); 7908 7909 PetscFunctionBegin; 7910 PetscValidHeaderSpecific(A,MAT_CLASSID,1); 7911 PetscValidType(A,1); 7912 if (!A->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7913 if (A->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7914 PetscValidHeaderSpecific(B,MAT_CLASSID,2); 7915 PetscValidType(B,2); 7916 ierr = MatPreallocated(B);CHKERRQ(ierr); 7917 if (!B->assembled) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7918 if (B->factortype) SETERRQ(((PetscObject)A)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7919 PetscValidPointer(C,3); 7920 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); 7921 if (fill == PETSC_DEFAULT || fill == PETSC_DECIDE) fill = 2.0; 7922 if (fill < 1.0) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_ARG_SIZ,"Expected fill=%G must be > 1.0",fill); 7923 ierr = MatPreallocated(A);CHKERRQ(ierr); 7924 7925 fA = A->ops->matmulttranspose; 7926 if (!fA) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"MatMatMultTranspose not supported for A of type %s",((PetscObject)A)->type_name); 7927 fB = B->ops->matmulttranspose; 7928 if (!fB) SETERRQ1(((PetscObject)A)->comm,PETSC_ERR_SUP,"MatMatMultTranspose not supported for B of type %s",((PetscObject)B)->type_name); 7929 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); 7930 7931 ierr = PetscLogEventBegin(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 7932 ierr = (*A->ops->matmulttranspose)(A,B,scall,fill,C);CHKERRQ(ierr); 7933 ierr = PetscLogEventEnd(MAT_MatMultTranspose,A,B,0,0);CHKERRQ(ierr); 7934 7935 PetscFunctionReturn(0); 7936 } 7937 7938 #undef __FUNCT__ 7939 #define __FUNCT__ "MatGetRedundantMatrix" 7940 /*@C 7941 MatGetRedundantMatrix - Create redundant matrices and put them into processors of subcommunicators. 7942 7943 Collective on Mat 7944 7945 Input Parameters: 7946 + mat - the matrix 7947 . nsubcomm - the number of subcommunicators (= number of redundant pareallel or sequential matrices) 7948 . subcomm - MPI communicator split from the communicator where mat resides in 7949 . mlocal_red - number of local rows of the redundant matrix 7950 - reuse - either MAT_INITIAL_MATRIX or MAT_REUSE_MATRIX 7951 7952 Output Parameter: 7953 . matredundant - redundant matrix 7954 7955 Notes: 7956 MAT_REUSE_MATRIX can only be used when the nonzero structure of the 7957 original matrix has not changed from that last call to MatGetRedundantMatrix(). 7958 7959 This routine creates the duplicated matrices in subcommunicators; you should NOT create them before 7960 calling it. 7961 7962 Only MPIAIJ matrix is supported. 7963 7964 Level: advanced 7965 7966 Concepts: subcommunicator 7967 Concepts: duplicate matrix 7968 7969 .seealso: MatDestroy() 7970 @*/ 7971 PetscErrorCode PETSCMAT_DLLEXPORT MatGetRedundantMatrix(Mat mat,PetscInt nsubcomm,MPI_Comm subcomm,PetscInt mlocal_red,MatReuse reuse,Mat *matredundant) 7972 { 7973 PetscErrorCode ierr; 7974 7975 PetscFunctionBegin; 7976 PetscValidHeaderSpecific(mat,MAT_CLASSID,1); 7977 if (nsubcomm && reuse == MAT_REUSE_MATRIX) { 7978 PetscValidPointer(*matredundant,6); 7979 PetscValidHeaderSpecific(*matredundant,MAT_CLASSID,6); 7980 } 7981 if (!mat->ops->getredundantmatrix) SETERRQ1(((PetscObject)mat)->comm,PETSC_ERR_SUP,"Mat type %s",((PetscObject)mat)->type_name); 7982 if (!mat->assembled) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix"); 7983 if (mat->factortype) SETERRQ(((PetscObject)mat)->comm,PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix"); 7984 ierr = MatPreallocated(mat);CHKERRQ(ierr); 7985 7986 ierr = PetscLogEventBegin(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 7987 ierr = (*mat->ops->getredundantmatrix)(mat,nsubcomm,subcomm,mlocal_red,reuse,matredundant);CHKERRQ(ierr); 7988 ierr = PetscLogEventEnd(MAT_GetRedundantMatrix,mat,0,0,0);CHKERRQ(ierr); 7989 PetscFunctionReturn(0); 7990 } 7991