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