Skip to main content
`Ctrl`+`K`

# petsc4py.PETSc.Mat

class petsc4py.PETSc.Mat

  Bases: `Object`

  Matrix object.

  Mat is described in the `PETSc manual`.

  See also

  `Mat`

  Enumerations

  `AssemblyType` | Matrix assembly type.
  `DuplicateOption` | Matrix duplicate option.
  `FactorShiftType` | Factored matrix shift type.
  `InfoType` | Matrix info type.
  `Option` | Matrix option.
  `OrderingType` | Factored matrix ordering type.
  `SORType` | Matrix SOR type.
  `SolverType` | Factored matrix solver type.
  `Stencil` | Associate structured grid coordinates with matrix indices.
  `Structure` | Matrix modification structure.
  `Type` | Matrix type.

  Methods Summary

  `H2OpusCompress`(tol) | Compress a hierarchical matrix.
  `H2OpusLowRankUpdate`(U[, V, s]) | Perform a low-rank update of the form `self` += sUVᵀ.
  `H2OpusOrthogonalize`() | Orthogonalize the basis tree of a hierarchical matrix.
  `HtoolGetPermutationSource`() | Get the permutation of source (column) indices computed by Htool.
  `HtoolGetPermutationTarget`() | Get the permutation of target (row) indices computed by Htool.
  `HtoolUsePermutation`(use) | Set whether to use the permutation computed by Htool.
  `HtoolUseRecompression`(use) | Set whether to recompress the matrix after assembly.
  `SOR`(b, x[, omega, sortype, shift, its, lits]) | Compute relaxation (SOR, Gauss-Seidel) sweeps.
  `allocateLMVM`(x, f) | Allocate all necessary common memory LMVM matrix.
  `appendOptionsPrefix`([prefix]) | Append to the prefix used for searching for options in the database.
  `assemble`([assembly]) | Assemble the matrix.
  `assemblyBegin`([assembly]) | Begin an assembling stage of the matrix.
  `assemblyEnd`([assembly]) | Complete an assembling stage of the matrix initiated with `assemblyBegin`.
  `axpy`(alpha, X[, structure]) | Perform the matrix summation `self` + = ɑ·X.
  `aypx`(alpha, X[, structure]) | Perform the matrix summation `self` = ɑ·`self` + X.
  `bindToCPU`(flg) | Mark a matrix to temporarily stay on the CPU.
  `boundToCPU`() | Query if a matrix is bound to the CPU.
  `chop`(tol) | Set entries smallest of tol (in absolute values) to zero.
  `conjugate`([out]) | Return the conjugate matrix.
  `convert`([mat_type, out]) | Convert the matrix type.
  `copy`([result, structure]) | Return a copy of the matrix.
  `create`([comm]) | Create the matrix.
  `createAIJ`(size[, bsize, nnz, csr, comm]) | Create a sparse `Type.AIJ` matrix, optionally preallocating.
  `createAIJCRL`(size[, bsize, nnz, csr, comm]) | Create a sparse `Type.AIJCRL` matrix.
  `createAIJWithArrays`(size, csr[, bsize, comm]) | Create a sparse `Type.AIJ` matrix with data in CSR format.
  `createBAIJ`(size, bsize[, nnz, csr, comm]) | Create a sparse blocked `Type.BAIJ` matrix, optionally preallocating.
  `createConstantDiagonal`(size, diag[, comm]) | Create a diagonal matrix of type `Type.CONSTANTDIAGONAL`.
  `createDense`(size[, bsize, array, comm]) | Create a `Type.DENSE` matrix.
  `createDenseCUDA`(size[, bsize, array, ...]) | Create a `Type.DENSECUDA` matrix with optional host and device data.
  `createDiagonal`(diag) | Create a diagonal matrix of type `Type.DIAGONAL`.
  `createH2OpusFromMat`(A[, coordinates, dist, ...]) | Create a hierarchical `Type.H2OPUS` matrix sampling from a provided operator.
  `createHermitianTranspose`(mat) | Create a `Type.HERMITIANTRANSPOSE` matrix that behaves like (A*)ᵀ.
  `createHtoolFromKernel`(size, spacedim, ...[, ...]) | Create a `Type.HTOOL` matrix using a kernel function defined in Python.
  `createIS`(size[, bsize, lgmapr, lgmapc, comm]) | Create a `Type.IS` matrix representing globally unassembled operators.
  `createLRC`(A, U, c, V) | Create a low-rank correction `Type.LRC` matrix representing A + UCVᵀ.
  `createNest`(mats[, isrows, iscols, comm]) | Create a `Type.NEST` matrix containing multiple submatrices.
  `createNormal`(mat) | Create a `Type.NORMAL` matrix representing AᵀA.
  `createNormalHermitian`(mat) | Create a `Type.NORMALHERMITIAN` matrix representing (A*)ᵀA.
  `createPython`(size[, context, comm]) | Create a `Type.PYTHON` matrix.
  `createSBAIJ`(size, bsize[, nnz, csr, comm]) | Create a sparse `Type.SBAIJ` matrix in symmetric block format.
  `createScatter`(scatter[, comm]) | Create a `Type.SCATTER` matrix from a vector scatter.
  `createSchurComplement`(A00, Ap00, A01, A10[, A11]) | Create a `Type.SCHURCOMPLEMENT` matrix.
  `createSubMatrices`(isrows[, iscols, submats]) | Return several sequential submatrices.
  `createSubMatrix`(isrow[, iscol, submat]) | Return a submatrix.
  `createSubMatrixVirtual`(A, isrow[, iscol]) | Create a `Type.SUBMATRIX` matrix that acts as a submatrix.
  `createTranspose`(mat) | Create a `Type.TRANSPOSE` matrix that behaves like Aᵀ.
  `createVecLeft`() | Return a left vector, a vector that the matrix vector product can be stored in.
  `createVecRight`() | Return a right vector, a vector that the matrix can be multiplied against.
  `createVecs`([side]) | Return vectors that can be used in matrix vector products.
  `destroy`() | Destroy the matrix.
  `diagonalScale`([L, R]) | Perform left and/or right diagonal scaling of the matrix.
  `duplicate`([copy]) | Return a clone of the matrix.
  `equal`(mat) | Return the result of matrix comparison.
  `factorCholesky`(isperm[, options]) | Perform an in-place Cholesky factorization.
  `factorICC`(isperm[, options]) | Perform an in-place an incomplete Cholesky factorization.
  `factorILU`(isrow, iscol[, options]) | Perform an in-place ILU factorization.
  `factorLU`(isrow, iscol[, options]) | Perform an in-place LU factorization.
  `factorNumericCholesky`(mat[, options]) | Not implemented.
  `factorNumericLU`(mat[, options]) | Not implemented.
  `factorSymbolicCholesky`(isperm[, options]) | Not implemented.
  `factorSymbolicICC`(isperm[, options]) | Not implemented.
  `factorSymbolicILU`(isrow, iscol[, options]) | Not implemented.
  `factorSymbolicLU`(mat, isrow, iscol[, options]) | Not implemented.
  `findZeroRows`() | Return the index set of empty rows.
  `fixISLocalEmpty`([fix]) | Compress out zero local rows from the local matrices.
  `getBlockSize`() | Return the matrix block size.
  `getBlockSizes`() | Return the row and column block sizes.
  `getColumnIJ`([symmetric, compressed]) | Return the CSC representation of the local sparsity pattern.
  `getColumnVector`(column[, result]) | Return the columnᵗʰ column vector of the matrix.
  `getDM`() | Return the DM defining the data layout of the matrix.
  `getDenseArray`([readonly]) | Return the array where the data is stored.
  `getDenseColumnVec`(i[, mode]) | Return the iᵗʰ column vector of the dense matrix.
  `getDenseLDA`() | Return the leading dimension of the array used by the dense matrix.
  `getDenseLocalMatrix`() | Return the local part of the dense matrix.
  `getDenseSubMatrix`([rbegin, rend, cbegin, cend]) | Get access to a submatrix of a `Type.DENSE` matrix.
  `getDiagonal`([result]) | Return the diagonal of the matrix.
  `getDiagonalBlock`() | Return the part of the matrix associated with the on-process coupling.
  `getISAllowRepeated`() | Get the flag for repeated entries in the local to global map.
  `getISLocalMat`() | Return the local matrix stored inside a `Type.IS` matrix.
  `getInertia`() | Return the inertia from a factored matrix.
  `getInfo`([info]) | Return summary information.
  `getLGMap`() | Return the local-to-global mappings.
  `getLMVMJ0`() | Get the initial Jacobian of the LMVM matrix.
  `getLMVMJ0KSP`() | Get the KSP of the LMVM matrix.
  `getLRCMats`() | Return the constituents of a `Type.LRC` matrix.
  `getLocalSize`() | Return the local number of rows and columns.
  `getLocalSubMatrix`(isrow, iscol[, submat]) | Return a reference to a submatrix specified in local numbering.
  `getMumpsCntl`(icntl) | Return the MUMPS parameter, `CNTL[icntl]`.
  `getMumpsIcntl`(icntl) | Return the MUMPS parameter, `ICNTL[icntl]`.
  `getMumpsInfo`(icntl) | Return the MUMPS parameter, `INFO[icntl]`.
  `getMumpsInfog`(icntl) | Return the MUMPS parameter, `INFOG[icntl]`.
  `getMumpsRinfo`(icntl) | Return the MUMPS parameter, `RINFO[icntl]`.
  `getMumpsRinfog`(icntl) | Return the MUMPS parameter, `RINFOG[icntl]`.
  `getNearNullSpace`() | Return the near-nullspace.
  `getNestISs`() | Return the index sets representing the row and column spaces.
  `getNestLocalISs`() | Return the local index sets representing the row and column spaces.
  `getNestSize`() | Return the number of rows and columns of the matrix.
  `getNestSubMatrix`(i, j) | Return a single submatrix.
  `getNullSpace`() | Return the nullspace.
  `getOption`(option) | Return the option value.
  `getOptionsPrefix`() | Return the prefix used for searching for options in the database.
  `getOrdering`(ord_type) | Return a reordering for a matrix to improve a LU factorization.
  `getOwnershipIS`() | Return the ranges of rows and columns owned by each process as index sets.
  `getOwnershipRange`() | Return the locally owned range of rows.
  `getOwnershipRangeColumn`() | Return the locally owned range of columns.
  `getOwnershipRanges`() | Return the range of rows owned by each process.
  `getOwnershipRangesColumn`() | Return the range of columns owned by each process.
  `getPythonContext`() | Return the instance of the class implementing the required Python methods.
  `getPythonType`() | Return the fully qualified Python name of the class used by the matrix.
  `getRedundantMatrix`(nsubcomm[, subcomm, out]) | Return redundant matrices on subcommunicators.
  `getRow`(row) | Return the column indices and values for the requested row.
  `getRowIJ`([symmetric, compressed]) | Return the CSR representation of the local sparsity pattern.
  `getRowSum`([result]) | Return the row-sum vector.
  `getSchurComplementSubMatrices`() | Return Schur complement sub-matrices.
  `getSize`() | Return the global number of rows and columns.
  `getSizes`() | Return the tuple of matrix layouts.
  `getTransposeMat`() | Return the internal matrix of a `Type.TRANSPOSE` matrix.
  `getTransposeNullSpace`() | Return the transpose nullspace.
  `getType`() | Return the type of the matrix.
  `getValue`(row, col) | Return the value in the (row, col) position.
  `getValues`(rows, cols[, values]) | Return the values in the `zip(rows, cols)` positions.
  `getValuesCSR`() | Return the CSR representation of the local part of the matrix.
  `getVecType`() | Return the vector type used by the matrix.
  `hermitianTranspose`([out]) | Return the transposed Hermitian matrix.
  `imagPart`([out]) | Return the imaginary part of the matrix.
  `increaseOverlap`(iset[, overlap]) | Increase the overlap of a index set.
  `invertBlockDiagonal`() | Return the inverse of the block-diagonal entries.
  `isAssembled`() | The boolean flag indicating if the matrix is assembled.
  `isHermitian`([tol]) | Return the boolean indicating if the matrix is Hermitian.
  `isHermitianKnown`() | Return the 2-tuple indicating if the matrix is known to be Hermitian.
  `isLinear`([n]) | Return whether the Mat is a linear operator.
  `isStructurallySymmetric`() | Return the boolean indicating if the matrix is structurally symmetric.
  `isSymmetric`([tol]) | Return the boolean indicating if the matrix is symmetric.
  `isSymmetricKnown`() | Return the 2-tuple indicating if the matrix is known to be symmetric.
  `isTranspose`([mat, tol]) | Return the result of matrix comparison with transposition.
  `kron`(mat[, result]) | Compute C, the Kronecker product of A and B.
  `load`(viewer) | Load a matrix.
  `matMatMult`(B, C[, result, fill]) | Perform matrix-matrix-matrix multiplication D=ABC.
  `matMult`(mat[, result, fill]) | Perform matrix-matrix multiplication C=AB.
  `matSolve`(B, X) | Solve AX=B, given a factored matrix A.
  `matTransposeMult`(mat[, result, fill]) | Perform matrix-matrix multiplication C=ABᵀ.
  `mult`(x, y) | Perform the matrix vector product y = A @ x.
  `multAdd`(x, v, y) | Perform the matrix vector product with addition y = A @ x + v.
  `multHermitian`(x, y) | Perform the Hermitian matrix vector product y = A^H @ x.
  `multHermitianAdd`(x, v, y) | Perform the Hermitian matrix vector product with addition y = A^H @ x + v.
  `multTranspose`(x, y) | Perform the transposed matrix vector product y = A^T @ x.
  `multTransposeAdd`(x, v, y) | Perform the transposed matrix vector product with addition y = A^T @ x + v.
  `norm`([norm_type]) | Compute the requested matrix norm.
  `permute`(row, col) | Return the permuted matrix.
  `preallocatorPreallocate`(A[, fill]) | Preallocate memory for a matrix using a preallocator matrix.
  `ptap`(P[, result, fill]) | Creates the matrix product C = PᵀAP.
  `rart`(R[, result, fill]) | Create the matrix product C = RARᵀ.
  `realPart`([out]) | Return the real part of the matrix.
  `reorderForNonzeroDiagonal`(isrow, iscol[, atol]) | Change a matrix ordering to remove zeros from the diagonal.
  `resetLMVM`([destructive]) | Flushes all of the accumulated updates out of the LMVM matrix.
  `restoreDenseColumnVec`(i[, mode, V]) | Restore the iᵗʰ column vector of the dense matrix.
  `restoreDenseSubMatrix`(mat) | Restore access to a submatrix of a `Type.DENSE` matrix.
  `restoreISLocalMat`(local) | Restore the local matrix obtained with `getISLocalMat`.
  `restoreLocalSubMatrix`(isrow, iscol, submat) | Restore a reference to a submatrix obtained with `getLocalSubMatrix`.
  `retrieveValues`() | Retrieve a copy of the matrix values previously stored with `storeValues`.
  `scale`(alpha) | Scale the matrix.
  `setBlockSize`(bsize) | Set the matrix block size (same for rows and columns).
  `setBlockSizes`(row_bsize, col_bsize) | Set the row and column block sizes.
  `setDM`(dm) | Set the DM defining the data layout of the matrix.
  `setDenseLDA`(lda) | Set the leading dimension of the array used by the dense matrix.
  `setDiagonal`(diag[, addv]) | Set the diagonal values of the matrix.
  `setFromOptions`() | Configure the matrix from the options database.
  `setISAllowRepeated`([allow]) | Allow repeated entries in the local to global map.
  `setISLocalMat`(local) | Set the local matrix stored inside a `Type.IS`.
  `setISPreallocation`(nnz, onnz) | Preallocate memory for a `Type.IS` parallel matrix.
  `setLGMap`(rmap[, cmap]) | Set the local-to-global mappings.
  `setLMVMJ0`(J0) | Set the initial Jacobian of the LMVM matrix.
  `setLMVMJ0KSP`(ksp) | Set the KSP of the LMVM matrix.
  `setLRCMats`(A, U[, c, V]) | Set the constituents of a `Type.LRC` matrix.
  `setMumpsCntl`(icntl, val) | Set a MUMPS parameter, `CNTL[icntl] = val`.
  `setMumpsIcntl`(icntl, ival) | Set a MUMPS parameter, `ICNTL[icntl] = ival`.
  `setNearNullSpace`(nsp) | Set the near-nullspace.
  `setNestVecType`(vec_type) | Set the vector type for a `Type.NEST` matrix.
  `setNullSpace`(nsp) | Set the nullspace.
  `setOption`(option, flag) | Set option.
  `setOptionsPrefix`([prefix]) | Set the prefix used for searching for options in the database.
  `setPreallocationCOO`(coo_i, coo_j) | Set preallocation using coordinate format with global indices.
  `setPreallocationCOOLocal`(coo_i, coo_j) | Set preallocation using coordinate format with local indices.
  `setPreallocationCSR`(csr) | Preallocate memory for the matrix with a CSR layout.
  `setPreallocationDense`(array) | Set the array used for storing matrix elements for a dense matrix.
  `setPreallocationNNZ`(nnz) | Preallocate memory for the matrix with a non-zero pattern.
  `setPythonContext`(context) | Set the instance of the class implementing the required Python methods.
  `setPythonType`(py_type) | Set the fully qualified Python name of the class to be used.
  `setRandom`([random]) | Set random values in the matrix.
  `setSizes`(size[, bsize]) | Set the local, global and block sizes.
  `setStencil`(dims[, starts, dof]) | Set matrix stencil.
  `setTransposeNullSpace`(nsp) | Set the transpose nullspace.
  `setTransposePrecursor`(out) | Set transpose precursor.
  `setType`(mat_type) | Set the matrix type.
  `setUnfactored`() | Set a factored matrix to be treated as unfactored.
  `setUp`() | Set up the internal data structures for using the matrix.
  `setValue`(row, col, value[, addv]) | Set a value to the `(row, col)` entry of the matrix.
  `setValueBlockedStagStencil`(row, col, value) | Not implemented.
  `setValueBlockedStencil`(row, col, value[, addv]) | Set a block of values to row and col stencil.
  `setValueLocal`(row, col, value[, addv]) | Set a value to the `(row, col)` entry of the matrix in local ordering.
  `setValueStagStencil`(row, col, value[, addv]) | Not implemented.
  `setValueStencil`(row, col, value[, addv]) | Set a value to row and col stencil.
  `setValues`(rows, cols, values[, addv]) | Set values to the rows ⊗ cols entries of the matrix.
  `setValuesBlocked`(rows, cols, values[, addv]) | Set values to the rows ⊗ col block entries of the matrix.
  `setValuesBlockedCSR`(I, J, V[, addv]) | Set values stored in block CSR format.
  `setValuesBlockedIJV`(I, J, V[, addv, rowmap]) | Set a subset of values stored in block CSR format.
  `setValuesBlockedLocal`(rows, cols, values[, addv]) | Set values to the rows ⊗ col block entries of the matrix in local ordering.
  `setValuesBlockedLocalCSR`(I, J, V[, addv]) | Set values stored in block CSR format.
  `setValuesBlockedLocalIJV`(I, J, V[, addv, rowmap]) | Set a subset of values stored in block CSR format.
  `setValuesBlockedLocalRCV`(R, C, V[, addv]) | Undocumented.
  `setValuesBlockedRCV`(R, C, V[, addv]) | Undocumented.
  `setValuesCOO`(coo_v[, addv]) | Set values after preallocation with coordinate format.
  `setValuesCSR`(I, J, V[, addv]) | Set values stored in CSR format.
  `setValuesIJV`(I, J, V[, addv, rowmap]) | Set a subset of values stored in CSR format.
  `setValuesLocal`(rows, cols, values[, addv]) | Set values to the rows ⊗ col entries of the matrix in local ordering.
  `setValuesLocalCSR`(I, J, V[, addv]) | Set values stored in CSR format.
  `setValuesLocalIJV`(I, J, V[, addv, rowmap]) | Set a subset of values stored in CSR format.
  `setValuesLocalRCV`(R, C, V[, addv]) | Undocumented.
  `setValuesRCV`(R, C, V[, addv]) | Undocumented.
  `setVariableBlockSizes`(blocks) | Set diagonal point-blocks of the matrix.
  `setVecType`(vec_type) | Set the vector type.
  `shift`(alpha) | Shift the matrix.
  `solve`(b, x) | Solve Ax=b, given a factored matrix.
  `solveAdd`(b, y, x) | Solve x=y+A⁻¹b, given a factored matrix.
  `solveBackward`(b, x) | Solve Ux=b, given a factored matrix A=LU.
  `solveForward`(b, x) | Solve Lx = b, given a factored matrix A = LU.
  `solveTranspose`(b, x) | Solve Aᵀx=b, given a factored matrix.
  `solveTransposeAdd`(b, y, x) | Solve x=y+A⁻ᵀb, given a factored matrix.
  `storeValues`() | Stash a copy of the matrix values.
  `toDLPack`([mode]) | Return a DLPack `PyCapsule` wrapping the vector data.
  `transpose`([out]) | Return the transposed matrix.
  `transposeMatMult`(mat[, result, fill]) | Perform matrix-matrix multiplication C=AᵀB.
  `updateLMVM`(x, f) | Adds (X-Xprev) and (F-Fprev) updates to LMVM matrix.
  `view`([viewer]) | View the matrix.
  `zeroEntries`() | Zero the entries of the matrix.
  `zeroRows`(rows[, diag, x, b]) | Zero selected rows of the matrix.
  `zeroRowsColumns`(rows[, diag, x, b]) | Zero selected rows and columns of the matrix.
  `zeroRowsColumnsLocal`(rows[, diag, x, b]) | Zero selected rows and columns of the matrix in local ordering.
  `zeroRowsColumnsStencil`(rows[, diag, x, b]) | Zero selected rows and columns of the matrix.
  `zeroRowsLocal`(rows[, diag, x, b]) | Zero selected rows of the matrix in local ordering.

  Attributes Summary

  `assembled` | The boolean flag indicating if the matrix is assembled.
  `block_size` | Matrix block size.
  `block_sizes` | Matrix row and column block sizes.
  `hermitian` | The boolean flag indicating if the matrix is Hermitian.
  `local_size` | Matrix local size.
  `owner_range` | Matrix local row range.
  `owner_ranges` | Matrix row ranges.
  `size` | Matrix global size.
  `sizes` | Matrix local and global sizes.
  `structsymm` | The boolean flag indicating if the matrix is structurally symmetric.
  `symmetric` | The boolean flag indicating if the matrix is symmetric.

  Methods Documentation

  H2OpusCompress(tol)

    Compress a hierarchical matrix.

    Collective.

    Parameters:

      tol (float) – The absolute truncation threshold.

    Return type:

      Self

    See also

    `MatH2OpusCompress`

    Source code at petsc4py/PETSc/Mat.pyx:5239

  H2OpusLowRankUpdate(U, V=None, s=1.0)

    Perform a low-rank update of the form `self` += sUVᵀ.

    Collective.

    Parameters:

      - U (Mat) – The dense low-rank update matrix.

      - V (Mat | None) – The dense low-rank update matrix. If `None`, `V = U`.

      - s (float) – The scaling factor.

    Return type:

      Self

    See also

    `MatH2OpusLowRankUpdate`

    Source code at petsc4py/PETSc/Mat.pyx:5258

  H2OpusOrthogonalize()

    Orthogonalize the basis tree of a hierarchical matrix.

    Collective.

    See also

    `MatH2OpusOrthogonalize`

    Source code at petsc4py/PETSc/Mat.pyx:5226

    Return type:

      Self

  HtoolGetPermutationSource()

    Get the permutation of source (column) indices computed by Htool.

    Not collective.

    Returns:

      The permutation index set for source indices.

    Return type:

      `IS`

    See also

    `HtoolGetPermutationTarget`, `MatHtoolGetPermutationSource`

    Source code at petsc4py/PETSc/Mat.pyx:5286

  HtoolGetPermutationTarget()

    Get the permutation of target (row) indices computed by Htool.

    Not collective.

    Returns:

      The permutation index set for target indices.

    Return type:

      `IS`

    See also

    `HtoolGetPermutationSource`, `MatHtoolGetPermutationTarget`

    Source code at petsc4py/PETSc/Mat.pyx:5305

  HtoolUsePermutation(use)

    Set whether to use the permutation computed by Htool.

    Logically collective.

    Parameters:

      use (bool) – Whether to use the permutation.

    Return type:

      Self

    See also

    `MatHtoolUsePermutation`

    Source code at petsc4py/PETSc/Mat.pyx:5324

  HtoolUseRecompression(use)

    Set whether to recompress the matrix after assembly.

    Logically collective.

    Parameters:

      use (bool) – Whether to use recompression.

    Return type:

      Self

    See also

    `MatHtoolUseRecompression`

    Source code at petsc4py/PETSc/Mat.pyx:5343

  SOR(b, x, omega=1.0, sortype=None, shift=0.0, its=1, lits=1)

    Compute relaxation (SOR, Gauss-Seidel) sweeps.

    Neighborwise collective.

    See also

    `MatSOR`

    Source code at petsc4py/PETSc/Mat.pyx:4072

    Parameters:

      - b (Vec)

      - x (Vec)

      - omega (float)

      - sortype (SORType | None)

      - shift (float)

      - its (int)

      - lits (int)

    Return type:

      None

  allocateLMVM(x, f)

    Allocate all necessary common memory LMVM matrix.

    Logically collective.

    Parameters:

      - x (Vec) – Solution vector.

      - f (Vec) – Function vector.

    Return type:

      None

    See also

    `MatLMVMAllocate`

    Source code at petsc4py/PETSc/Mat.pyx:5426

  appendOptionsPrefix(prefix=None)

    Append to the prefix used for searching for options in the database.

    Logically collective.

    See also

    Working with PETSc options, `setOptionsPrefix`, `MatAppendOptionsPrefix`

    Source code at petsc4py/PETSc/Mat.pyx:1960

    Parameters:

      prefix (str | None)

    Return type:

      None

  assemble(assembly=None)

    Assemble the matrix.

    Collective.

    Parameters:

      assembly (MatAssemblySpec) – The assembly type.

    Return type:

      None

    See also

    `assemblyBegin`, `assemblyEnd`

    Source code at petsc4py/PETSc/Mat.pyx:3585

  assemblyBegin(assembly=None)

    Begin an assembling stage of the matrix.

    Collective.

    Parameters:

      assembly (MatAssemblySpec) – The assembly type.

    Return type:

      None

    See also

    `assemblyEnd`, `assemble`, `MatAssemblyBegin`

    Source code at petsc4py/PETSc/Mat.pyx:3549

  assemblyEnd(assembly=None)

    Complete an assembling stage of the matrix initiated with `assemblyBegin`.

    Collective.

    Parameters:

      assembly (MatAssemblySpec) – The assembly type.

    Return type:

      None

    See also

    `assemblyBegin`, `assemble`, `MatAssemblyEnd`

    Source code at petsc4py/PETSc/Mat.pyx:3567

  axpy(alpha, X, structure=None)

    Perform the matrix summation `self` + = ɑ·X.

    Collective.

    Parameters:

      - alpha (Scalar) – The scalar.

      - X (Mat) – The matrix to be added.

      - structure (Structure | None) – The structure of the operation.

    Return type:

      None

    See also

    `MatAXPY`

    Source code at petsc4py/PETSc/Mat.pyx:4400

  aypx(alpha, X, structure=None)

    Perform the matrix summation `self` = ɑ·`self` + X.

    Collective.

    Parameters:

      - alpha (Scalar) – The scalar.

      - X (Mat) – The matrix to be added.

      - structure (Structure | None) – The structure of the operation.

    Return type:

      None

    See also

    `MatAYPX`

    Source code at petsc4py/PETSc/Mat.pyx:4423

  bindToCPU(flg)

    Mark a matrix to temporarily stay on the CPU.

    Collective.

    Once marked, perform computations on the CPU.

    Parameters:

      flg (bool) – Bind to the CPU if `True`.

    Return type:

      None

    See also

    `MatBindToCPU`

    Source code at petsc4py/PETSc/Mat.pyx:4767

  boundToCPU()

    Query if a matrix is bound to the CPU.

    Not collective.

    See also

    `MatBoundToCPU`

    Source code at petsc4py/PETSc/Mat.pyx:4787

    Return type:

      bool

  chop(tol)

    Set entries smallest of tol (in absolute values) to zero.

    Collective.

    See also

    `MatFilter`

    Source code at petsc4py/PETSc/Mat.pyx:4368

    Parameters:

      tol (float)

    Return type:

      None

  conjugate(out=None)

    Return the conjugate matrix.

    Collective.

    Parameters:

      out (Mat | None) – Optional return matrix. If `None`, the operation is performed in-place. Otherwise, the operation is performed on `out`.

    Return type:

      Mat

    See also

    `realPart`, `imagPart`, `MatConjugate`

    Source code at petsc4py/PETSc/Mat.pyx:2422

  convert(mat_type=None, out=None)

    Convert the matrix type.

    Collective.

    Parameters:

      - mat_type (Type | str | None) – The type of the new matrix. If `None` uses `Type.SAME`.

      - out (Mat | None) – Optional return matrix. If `None`, inplace conversion is performed. Otherwise, the matrix is reused.

    Return type:

      Mat

    See also

    `MatConvert`

    Source code at petsc4py/PETSc/Mat.pyx:2278

  copy(result=None, structure=None)

    Return a copy of the matrix.

    Collective.

    Parameters:

      - result (Mat | None) – Optional return matrix. If `None`, it is internally created.

      - structure (Structure | None) – The copy structure. Only relevant if `result` is not `None`.

    Return type:

      Mat

    See also

    `MatCopy`, `MatDuplicate`

    Source code at petsc4py/PETSc/Mat.pyx:2233

  create(comm=None)

    Create the matrix.

    Collective.

    Once created, the user should call `setType` or `setFromOptions` before using the matrix. Alternatively, specific creation routines such as `createAIJ` or `createBAIJ` can be used.

    Parameters:

      comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `destroy`, `MatCreate`

    Source code at petsc4py/PETSc/Mat.pyx:516

  createAIJ(size, bsize=None, nnz=None, csr=None, comm=None)

    Create a sparse `Type.AIJ` matrix, optionally preallocating.

    Collective.

    To preallocate the matrix the user can either pass `nnz` or `csr` describing the sparsity. If neither is set then preallocation will not occur. Consult the `PETSc manual` for more information.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - nnz (NNZSpec | None) – Optional non-zeros preallocation pattern.

      - csr (CSRSpec | CSRIndicesSpec | None) – Optional compressed sparse row layout information. If provided, it takes precedence on `nnz`.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `setSizes`, `createBAIJ`, `MATAIJ`, `MATSEQAIJ`, `MATMPIAIJ`, `MatCreateAIJ`, `MatSeqAIJSetPreallocation`, `MatSeqAIJSetPreallocationCSR`

    Source code at petsc4py/PETSc/Mat.pyx:721

  createAIJCRL(size, bsize=None, nnz=None, csr=None, comm=None)

    Create a sparse `Type.AIJCRL` matrix.

    Collective.

    This is similar to `Type.AIJ` matrices but stores some additional information that improves vectorization for the matrix-vector product.

    To preallocate the matrix the user can either pass `nnz` or `csr` describing the sparsity. If neither is set then preallocation will not occur. Consult the `PETSc manual` for more information.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - nnz (NNZSpec | None) – Optional non-zeros preallocation pattern.

      - csr (CSRSpec | CSRIndicesSpec | None) – Optional compressed sparse row layout information. If provided, it takes precedence on `nnz`.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `createAIJ`, `createBAIJ`, `MatCreateSeqAIJCRL`, `MatCreateMPIAIJCRL`

    Source code at petsc4py/PETSc/Mat.pyx:854

  createAIJWithArrays(size, csr, bsize=None, comm=None)

    Create a sparse `Type.AIJ` matrix with data in CSR format.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - csr (CSRSpec | tuple[CSRSpec, CSRSpec]) – Local matrix data in compressed sparse row format.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    Notes

    For `Type.SEQAIJ` matrices, the `csr` data is not copied. For `Type.MPIAIJ` matrices, the `csr` data is not copied only in the case it represents on-process and off-process information.

    See also

    `createAIJ`, `MatCreateSeqAIJWithArrays`, `MatCreateMPIAIJWithArrays`, `MatCreateMPIAIJWithSplitArrays`

    Source code at petsc4py/PETSc/Mat.pyx:1048

  createBAIJ(size, bsize, nnz=None, csr=None, comm=None)

    Create a sparse blocked `Type.BAIJ` matrix, optionally preallocating.

    Collective.

    To preallocate the matrix the user can either pass `nnz` or `csr` describing the sparsity. If neither is set then preallocation will not occur. Consult the `PETSc manual` for more information.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec) – Matrix block size.

      - nnz (NNZSpec | None) – Optional non-zeros preallocation pattern for block rows.

      - csr (CSRSpec | CSRIndicesSpec | None) – Optional block-compressed sparse row layout information. If provided, it takes precedence on `nnz`.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `setSizes`, `createAIJ`, `MATBAIJ`, `MATSEQBAIJ`, `MATMPIBAIJ`, `MatCreateBAIJ`

    Source code at petsc4py/PETSc/Mat.pyx:766

  createConstantDiagonal(size, diag, comm=None)

    Create a diagonal matrix of type `Type.CONSTANTDIAGONAL`.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - diag (float) – The diagonal value.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `createDiagonal`

    Source code at petsc4py/PETSc/Mat.pyx:1770

  createDense(size, bsize=None, array=None, comm=None)

    Create a `Type.DENSE` matrix.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - array (Sequence[Scalar] | None) – Optional matrix data. If `None`, memory is internally allocated.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `createDenseCUDA`, `MATDENSE`, `MatCreateDense`

    Source code at petsc4py/PETSc/Mat.pyx:1139

  createDenseCUDA(size, bsize=None, array=None, cudahandle=None, comm=None)

    Create a `Type.DENSECUDA` matrix with optional host and device data.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - array (Sequence[Scalar] | None) – Host data. Will be lazily allocated if `None`.

      - cudahandle (int | None) – Address of the array on the GPU. Will be lazily allocated if `None`. If `cudahandle` is provided, `array` will be ignored.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `createDense`, `MatCreateDenseCUDA`

    Source code at petsc4py/PETSc/Mat.pyx:1175

  createDiagonal(diag)

    Create a diagonal matrix of type `Type.DIAGONAL`.

    Collective.

    Parameters:

      diag (Vec) – The vector holding diagonal values.

    Return type:

      Self

    See also

    `createConstantDiagonal`

    Source code at petsc4py/PETSc/Mat.pyx:1803

  createH2OpusFromMat(A, coordinates=None, dist=None, eta=None, leafsize=None, maxrank=None, bs=None, rtol=None)

    Create a hierarchical `Type.H2OPUS` matrix sampling from a provided operator.

    Collective.

    Parameters:

      - A (Mat) – Matrix to be sampled.

      - coordinates (Sequence[Scalar] | None) – Coordinates of the points.

      - dist (bool | None) – Whether or not coordinates are distributed, defaults to `False`.

      - eta (float | None) – Admissibility condition tolerance, defaults to `DECIDE`.

      - leafsize (int | None) – Leaf size in cluster tree, defaults to `DECIDE`.

      - maxrank (int | None) – Maximum rank permitted, defaults to `DECIDE`.

      - bs (int | None) – Maximum number of samples to take concurrently, defaults to `DECIDE`.

      - rtol (float | None) – Relative tolerance for construction, defaults to `DECIDE`.

    Return type:

      Self

    Notes

    See `MatCreateH2OpusFromMat` for the appropriate database options.

    See also

    Working with PETSc options, `MatCreateH2OpusFromMat`

    Source code at petsc4py/PETSc/Mat.pyx:1546

  createHermitianTranspose(mat)

    Create a `Type.HERMITIANTRANSPOSE` matrix that behaves like (A*)ᵀ.

    Collective.

    Parameters:

      mat (Mat) – Matrix A to represent the Hermitian transpose of.

    Return type:

      Self

    Notes

    The Hermitian transpose is never actually formed.

    See also

    `createNormal`, `createNormalHermitian`, `MATHERMITIANTRANSPOSEVIRTUAL`, `MatCreateHermitianTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:1375

  createHtoolFromKernel(size, spacedim, coords_target, coords_source, kernel, kernelctx=None, comm=None)

    Create a `Type.HTOOL` matrix using a kernel function defined in Python.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - spacedim (int) – Dimension of the coordinate space.

      - coords_target (Sequence[Scalar]) – Local target (row) coordinates, shape `(m, spacedim)`.

      - coords_source (Sequence[Scalar]) – Local source (column) coordinates, shape `(n, spacedim)`.

      - kernel (MatHtoolKernelFunction) – Python callable with signature `kernel(sdim, M, N, rows, cols, v, ctx)` that fills the submatrix `v[i, j]` for target index `rows[i]` and source index `cols[j]`. `v` has shape `(M, N)` in column-major order.

      - kernelctx (Any) – Optional context passed as the last argument to `kernel`.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    Notes

    This function is called while the Python Global Interpreter Lock (GIL) is held. As a result, pure Python implementations will not scale with multithreading. For better performance, users should delegate heavy computations to compiled code that releases the GIL. This allows parallel execution inside threaded regions. For maximum performance, consider implementing the generator directly in C or C++ instead of using the Python interface. See `MatCreateHtoolFromKernel` for the appropriate database options.

    See also

    Working with PETSc options, `MatCreateHtoolFromKernel`, `HtoolGetPermutationSource`, `HtoolGetPermutationTarget`, `HtoolUsePermutation`, `HtoolUseRecompression`

    Source code at petsc4py/PETSc/Mat.pyx:1627

  createIS(size, bsize=None, lgmapr=None, lgmapc=None, comm=None)

    Create a `Type.IS` matrix representing globally unassembled operators.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

      - lgmapr (LGMap | None) – Optional local-to-global mapping for the rows. If `None`, the local row space matches the global row space.

      - lgmapc (LGMap | None) – Optional local-to-global mapping for the columns. If `None`, the local column space matches the global column space.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `MATIS`

    Source code at petsc4py/PETSc/Mat.pyx:1717

  createLRC(A, U, c, V)

    Create a low-rank correction `Type.LRC` matrix representing A + UCVᵀ.

    Collective.

    Parameters:

      - A (Mat | None) – Sparse matrix, can be `None`.

      - U (Mat) – Dense rectangular matrix.

      - c (Vec | None) – Vector containing the diagonal of `C`, can be `None`.

      - V (Mat | None) – Dense rectangular matrix, can be set to `U` or ‘None’.

    Return type:

      Self

    Notes

    The matrix A + UCVᵀ is never actually formed.

    C is a diagonal matrix (represented as a vector) of order k, where k is the number of columns of both `U` and `V`.

    If A is `None` then the new object behaves like a low-rank matrix UCVᵀ.

    Use the same matrix for `V` and `U` (or `V=None`) for a symmetric low-rank correction, A + UCUᵀ.

    If `c` is `None` then the low-rank correction is just U*Vᵀ. If a sequential `c` vector is used for a parallel matrix, PETSc assumes that the values of the vector are consistently set across processors.

    See also

    `MATLRC`, `MatCreateLRC`

    Source code at petsc4py/PETSc/Mat.pyx:1400

  createNest(mats, isrows=None, iscols=None, comm=None)

    Create a `Type.NEST` matrix containing multiple submatrices.

    Collective.

    Parameters:

      - mats (Sequence[Sequence[Mat]]) – Iterable of matrix block rows with size `len(isrows)`. Each matrix block row must be of size `len(iscols)`. Empty submatrices can be set with `None`.

      - isrows (Sequence[IS] | None) – Index set for each nested row block, defaults to contiguous ordering.

      - iscols (Sequence[IS] | None) – Index set for each nested column block, defaults to contiguous ordering.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `MatCreateNest`, `MATNEST`

    Source code at petsc4py/PETSc/Mat.pyx:1479

  createNormal(mat)

    Create a `Type.NORMAL` matrix representing AᵀA.

    Collective.

    Parameters:

      mat (Mat) – The (possibly rectangular) matrix A.

    Return type:

      Self

    Notes

    The product AᵀA is never actually formed. Instead A and Aᵀ are used during `mult` and various other matrix operations.

    See also

    `MATNORMAL`, `MatCreateNormal`

    Source code at petsc4py/PETSc/Mat.pyx:1280

  createNormalHermitian(mat)

    Create a `Type.NORMALHERMITIAN` matrix representing (A*)ᵀA.

    Collective.

    Parameters:

      mat (Mat) – The (possibly rectangular) matrix A.

    Return type:

      Self

    Notes

    The product (A*)ᵀA is never actually formed.

    See also

    `createHermitianTranspose`, `MATNORMAL`, `MATNORMALHERMITIAN`, `MatCreateNormalHermitian`

    Source code at petsc4py/PETSc/Mat.pyx:1350

  createPython(size, context=None, comm=None)

    Create a `Type.PYTHON` matrix.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - context (Any) – An instance of the Python class implementing the required methods.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    PETSc Python matrix type, `setType`, `setPythonContext`, `Type.PYTHON`

    Source code at petsc4py/PETSc/Mat.pyx:1826

  createSBAIJ(size, bsize, nnz=None, csr=None, comm=None)

    Create a sparse `Type.SBAIJ` matrix in symmetric block format.

    Collective.

    To preallocate the matrix the user can either pass `nnz` or `csr` describing the sparsity. If neither is set then preallocation will not occur. Consult the `PETSc manual` for more information.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec) – Matrix block size.

      - nnz (NNZSpec | None) – Optional upper-triangular (including diagonal) non-zeros preallocation pattern for block rows.

      - csr (CSRSpec | CSRIndicesSpec | None) – Optional block-compressed sparse row layout information. If provided, it takes precedence on `nnz`.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `createAIJ`, `createBAIJ`, `MatCreateSBAIJ`

    Source code at petsc4py/PETSc/Mat.pyx:810

  createScatter(scatter, comm=None)

    Create a `Type.SCATTER` matrix from a vector scatter.

    Collective.

    Parameters:

      - scatter (Scatter) – Vector scatter.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `MATSCATTER`, `MatCreateScatter`

    Source code at petsc4py/PETSc/Mat.pyx:1256

  createSchurComplement(A00, Ap00, A01, A10, A11=None)

    Create a `Type.SCHURCOMPLEMENT` matrix.

    Collective.

    Parameters:

      - A00 (Mat) – the upper-left block of the original matrix A = [A00 A01; A10 A11].

      - Ap00 (Mat) – used to construct the preconditioner used in ksp(A00,Ap00) to approximate the action of A00^{-1}.

      - A01 (Mat) – the upper-right block of the original matrix A = [A00 A01; A10 A11].

      - A10 (Mat) – the lower-left block of the original matrix A = [A00 A01; A10 A11].

      - A11 (Mat | None) – Optional lower-right block of the original matrix A = [A00 A01; A10 A11].

    Return type:

      Self

    See also

    `MatCreateSchurComplement`

    Source code at petsc4py/PETSc/Mat.pyx:4216

  createSubMatrices(isrows, iscols=None, submats=None)

    Return several sequential submatrices.

    Collective.

    Parameters:

      - isrows (IS | Sequence[IS]) – Row index sets.

      - iscols (IS | Sequence[IS] | None) – Column index sets. If `None`, `iscols = isrows`.

      - submats (Mat | Sequence[Mat] | None) – Optional resultant matrices. When `None`, new matrices are created, and `MAT_INITIAL_MATRIX` is used. When not `None`, the matrices are reused with `MAT_REUSE_MATRIX`.

    Return type:

      Sequence[Mat]

    See also

    `MatCreateSubMatrices`

    Source code at petsc4py/PETSc/Mat.pyx:4159

  createSubMatrix(isrow, iscol=None, submat=None)

    Return a submatrix.

    Collective.

    Parameters:

      - isrow (IS) – Row index set.

      - iscol (IS | None) – Column index set. If `None`, `iscol = isrow`.

      - submat (Mat | None) – Optional resultant matrix. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

    Return type:

      Mat

    See also

    `MatCreateSubMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:4129

  createSubMatrixVirtual(A, isrow, iscol=None)

    Create a `Type.SUBMATRIX` matrix that acts as a submatrix.

    Collective.

    Parameters:

      - A (Mat) – Matrix to extract submatrix from.

      - isrow (IS) – Rows present in the submatrix.

      - iscol (IS | None) – Columns present in the submatrix, defaults to `isrow`.

    Return type:

      Self

    See also

    `MatCreateSubMatrixVirtual`

    Source code at petsc4py/PETSc/Mat.pyx:1454

  createTranspose(mat)

    Create a `Type.TRANSPOSE` matrix that behaves like Aᵀ.

    Collective.

    Parameters:

      mat (Mat) – Matrix A to represent the transpose of.

    Return type:

      Self

    Notes

    The transpose is never actually formed. Instead `multTranspose` is called whenever the matrix-vector product is computed.

    See also

    `createNormal`, `MatCreateTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:1305

  createVecLeft()

    Return a left vector, a vector that the matrix vector product can be stored in.

    Collective.

    See also

    `createVecs`, `createVecRight`, `MatCreateVecs`

    Source code at petsc4py/PETSc/Mat.pyx:3685

    Return type:

      Vec

  createVecRight()

    Return a right vector, a vector that the matrix can be multiplied against.

    Collective.

    See also

    `createVecs`, `createVecLeft`, `MatCreateVecs`

    Source code at petsc4py/PETSc/Mat.pyx:3671

    Return type:

      Vec

  createVecs(side=None)

    Return vectors that can be used in matrix vector products.

    Collective.

    Parameters:

      side (Literal['r', 'R', 'right', 'Right', 'RIGHT', 'l', 'L', 'left', 'Left', 'LEFT'] | None) – If `None` returns a 2-tuple of vectors `(right, left)`. Otherwise it just returns a left or right vector.

    Return type:

      Vec | tuple[Vec, Vec]

    Notes

    `right` is a vector that the matrix can be multiplied against. `left` is a vector that the matrix-vector product can be stored in.

    See also

    `createVecLeft`, `createVecRight`, `MatCreateVecs`

    Source code at petsc4py/PETSc/Mat.pyx:3632

  destroy()

    Destroy the matrix.

    Collective.

    See also

    `create`, `MatDestroy`

    Source code at petsc4py/PETSc/Mat.pyx:503

    Return type:

      Self

  diagonalScale(L=None, R=None)

    Perform left and/or right diagonal scaling of the matrix.

    Collective.

    Parameters:

      - L (Vec | None) – Optional left scaling vector.

      - R (Vec | None) – Optional right scaling vector.

    Return type:

      None

    See also

    `MatDiagonalScale`

    Source code at petsc4py/PETSc/Mat.pyx:3824

  duplicate(copy=False)

    Return a clone of the matrix.

    Collective.

    Parameters:

      copy (DuplicateOption | bool) – If `True`, it also copies the values.

    Return type:

      Mat

    See also

    `MatDuplicate`

    Source code at petsc4py/PETSc/Mat.pyx:2213

  equal(mat)

    Return the result of matrix comparison.

    Collective.

    See also

    `MatEqual`

    Source code at petsc4py/PETSc/Mat.pyx:2466

    Parameters:

      mat (Mat)

    Return type:

      bool

  factorCholesky(isperm, options=None)

    Perform an in-place Cholesky factorization.

    Collective.

    Parameters:

      - isperm (IS) – The row and column permutations.

      - options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include `fill`, the expected fill as a ratio of the original fill.

    Return type:

      None

    See also

    `factorLU`, `MatCholeskyFactor`

    Source code at petsc4py/PETSc/Mat.pyx:4931

  factorICC(isperm, options=None)

    Perform an in-place an incomplete Cholesky factorization.

    Collective.

    Parameters:

      - isperm (IS) – The row and column permutations

      - options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include `fill`, the expected fill as a ratio of the original fill.

    Return type:

      None

    See also

    `factorILU`, `MatICCFactor`

    Source code at petsc4py/PETSc/Mat.pyx:4964

  factorILU(isrow, iscol, options=None)

    Perform an in-place ILU factorization.

    Collective.

    Parameters:

      - isrow (IS) – The row permutation.

      - iscol (IS) – The column permutation.

      - options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include `levels`, the number of levels of fill, `fill`, the expected fill as a ratio of the original fill, and `dtcol`, the pivot tolerance where `0` indicates no pivot and `1` indicates full column pivoting.

    Return type:

      None

    See also

    `MatILUFactor`

    Source code at petsc4py/PETSc/Mat.pyx:4897

  factorLU(isrow, iscol, options=None)

    Perform an in-place LU factorization.

    Collective.

    Parameters:

      - isrow (IS) – The row permutation.

      - iscol (IS) – The column permutation.

      - options (dict[str, Any] | None) – An optional dictionary of options for the factorization. These include `fill`, the expected fill as a ratio of the original fill and `dtcol`, the pivot tolerance where `0` indicates no pivot and `1` indicates full column pivoting.

    Return type:

      None

    See also

    `MatLUFactor`

    Source code at petsc4py/PETSc/Mat.pyx:4859

  factorNumericCholesky(mat, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4960

    Parameters:

      mat (Mat)

    Return type:

      None

  factorNumericLU(mat, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4893

    Parameters:

      mat (Mat)

    Return type:

      None

  factorSymbolicCholesky(isperm, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4956

    Parameters:

      isperm (IS)

    Return type:

      None

  factorSymbolicICC(isperm, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4989

    Parameters:

      isperm (IS)

    Return type:

      None

  factorSymbolicILU(isrow, iscol, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4927

    Parameters:

      - isrow (IS)

      - iscol (IS)

    Return type:

      None

  factorSymbolicLU(mat, isrow, iscol, options=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:4889

    Parameters:

      - mat (Mat)

      - isrow (IS)

      - iscol (IS)

    Return type:

      None

  findZeroRows()

    Return the index set of empty rows.

    Collective.

    See also

    `MatFindZeroRows`

    Source code at petsc4py/PETSc/Mat.pyx:3618

    Return type:

      IS

  fixISLocalEmpty(fix=True)

    Compress out zero local rows from the local matrices.

    Collective.

    Parameters:

      fix (bool) – When `True`, new local matrices and local to global maps are generated during the final assembly process.

    Return type:

      None

    See also

    `MatISFixLocalEmpty`

    Source code at petsc4py/PETSc/Mat.pyx:5064

  getBlockSize()

    Return the matrix block size.

    Not collective.

    See also

    `getBlockSize`, `MatGetBlockSize`

    Source code at petsc4py/PETSc/Mat.pyx:2083

    Return type:

      int

  getBlockSizes()

    Return the row and column block sizes.

    Not collective.

    See also

    `getBlockSize`, `MatGetBlockSizes`

    Source code at petsc4py/PETSc/Mat.pyx:2097

    Return type:

      tuple[int, int]

  getColumnIJ(symmetric=False, compressed=False)

    Return the CSC representation of the local sparsity pattern.

    Collective.

    Parameters:

      - symmetric (bool) – If `True`, return the symmetrized graph.

      - compressed (bool) – If `True`, return the compressed graph.

    Return type:

      tuple[ArrayInt, ArrayInt]

    See also

    `MatGetRowIJ`

    Source code at petsc4py/PETSc/Mat.pyx:2744

  getColumnVector(column, result=None)

    Return the columnᵗʰ column vector of the matrix.

    Collective.

    Parameters:

      - column (int) – Column index.

      - result (Vec | None) – Optional vector to store the result.

    Return type:

      Vec

    See also

    `MatGetColumnVector`

    Source code at petsc4py/PETSc/Mat.pyx:3705

  getDM()

    Return the DM defining the data layout of the matrix.

    Not collective.

    See also

    `MatGetDM`

    Source code at petsc4py/PETSc/Mat.pyx:6079

    Return type:

      DM

  getDenseArray(readonly=False)

    Return the array where the data is stored.

    Not collective.

    Parameters:

      readonly (bool) – Enable to obtain a read only array.

    Return type:

      ArrayScalar

    See also

    `MatDenseGetArrayRead`, `MatDenseGetArray`

    Source code at petsc4py/PETSc/Mat.pyx:5821

  getDenseColumnVec(i, mode='rw')

    Return the iᵗʰ column vector of the dense matrix.

    Collective.

    Parameters:

      - i (int) – The column index to access.

      - mode (AccessModeSpec) – The access type of the vector to be returned.

    Return type:

      Vec

    See also

    `restoreDenseColumnVec`, `MatDenseGetColumnVec`, `MatDenseGetColumnVecRead`, `MatDenseGetColumnVecWrite`

    Source code at petsc4py/PETSc/Mat.pyx:5930

  getDenseLDA()

    Return the leading dimension of the array used by the dense matrix.

    Not collective.

    See also

    `MatDenseGetLDA`

    Source code at petsc4py/PETSc/Mat.pyx:5807

    Return type:

      int

  getDenseLocalMatrix()

    Return the local part of the dense matrix.

    Not collective.

    See also

    `MatDenseGetLocalMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:5862

    Return type:

      Mat

  getDenseSubMatrix(rbegin=DECIDE, rend=DECIDE, cbegin=DECIDE, cend=DECIDE)

    Get access to a submatrix of a `Type.DENSE` matrix.

    Collective.

    Parameters:

      - rbegin (int) – the first global row index.

      - rend (int) – the global row index past the last one.

      - cbegin (int) – the first global column index.

      - cend (int) – the global column index past the last one.

    Return type:

      Mat

    See also

    `restoreDenseSubMatrix`, `MatDenseGetSubMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:5877

  getDiagonal(result=None)

    Return the diagonal of the matrix.

    Collective.

    Parameters:

      result (Vec | None) – Optional vector to store the result.

    Return type:

      Vec

    See also

    `setDiagonal`, `MatGetDiagonal`

    Source code at petsc4py/PETSc/Mat.pyx:3760

  getDiagonalBlock()

    Return the part of the matrix associated with the on-process coupling.

    Not collective.

    See also

    `MatGetDiagonalBlock`

    Source code at petsc4py/PETSc/Mat.pyx:4101

    Return type:

      Mat

  getISAllowRepeated()

    Get the flag for repeated entries in the local to global map.

    Not collective.

    See also

    `setISAllowRepeated`, `MatISGetAllowRepeated`

    Source code at petsc4py/PETSc/Mat.pyx:5050

    Return type:

      bool

  getISLocalMat()

    Return the local matrix stored inside a `Type.IS` matrix.

    Not collective.

    See also

    `MatISGetLocalMat`

    Source code at petsc4py/PETSc/Mat.pyx:5083

    Return type:

      Mat

  getInertia()

    Return the inertia from a factored matrix.

    Collective.

    The matrix must have been factored by calling `factorCholesky`.

    Returns:

      - n (`int`) – The number of negative eigenvalues.

      - z (`int`) – The number of zero eigenvalues.

      - p (`int`) – The number of positive eigenvalues.

    Return type:

      tuple[int, int, int]

    See also

    `MatGetInertia`

    Source code at petsc4py/PETSc/Mat.pyx:4993

  getInfo(info=None)

    Return summary information.

    Collective.

    Parameters:

      info (InfoType | None) – If `None`, it uses `InfoType.GLOBAL_SUM`.

    Return type:

      dict[str, float]

    See also

    `MatInfo`, `MatGetInfo`

    Source code at petsc4py/PETSc/Mat.pyx:2193

  getLGMap()

    Return the local-to-global mappings.

    Not collective.

    See also

    `setLGMap`, `MatGetLocalToGlobalMapping`

    Source code at petsc4py/PETSc/Mat.pyx:3031

    Return type:

      tuple[LGMap, LGMap]

  getLMVMJ0()

    Get the initial Jacobian of the LMVM matrix.

    Not collective.

    See also

    `setLMVMJ0`, `MatLMVMGetJ0`

    Source code at petsc4py/PETSc/Mat.pyx:5364

    Return type:

      Mat

  getLMVMJ0KSP()

    Get the KSP of the LMVM matrix.

    Not collective.

    See also

    `setLMVMJ0KSP`, `MatLMVMGetJ0KSP`

    Source code at petsc4py/PETSc/Mat.pyx:5395

    Return type:

      Mat

  getLRCMats()

    Return the constituents of a `Type.LRC` matrix.

    Not collective.

    Returns:

      - A (`Mat`) – The `A` matrix.

      - U (`Mat`) – The first dense rectangular matrix.

      - c (`Vec`) – The sequential vector containing the diagonal of `C`.

      - V (`Mat`) – The second dense rectangular matrix.

    Return type:

      tuple[Mat, Mat, Vec, Mat]

    See also

    `MatLRCGetMats`

    Source code at petsc4py/PETSc/Mat.pyx:5165

  getLocalSize()

    Return the local number of rows and columns.

    Not collective.

    See also

    `getSize`, `MatGetLocalSize`

    Source code at petsc4py/PETSc/Mat.pyx:2053

    Return type:

      tuple[int, int]

  getLocalSubMatrix(isrow, iscol, submat=None)

    Return a reference to a submatrix specified in local numbering.

    Collective.

    Parameters:

      - isrow (IS) – Row index set.

      - iscol (IS) – Column index set.

      - submat (Mat | None) – Optional resultant matrix. When `None`, a new matrix is created. When not `None`, the matrix is first destroyed and then recreated.

    Return type:

      Mat

    See also

    `restoreLocalSubMatrix`, `MatGetLocalSubMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:4271

  getMumpsCntl(icntl)

    Return the MUMPS parameter, `CNTL[icntl]`.

    Logically collective.

    See also

    Working with PETSc options, `MatMumpsGetCntl`

    Source code at petsc4py/PETSc/Mat.pyx:5542

    Parameters:

      icntl (int)

    Return type:

      float

  getMumpsIcntl(icntl)

    Return the MUMPS parameter, `ICNTL[icntl]`.

    Logically collective.

    See also

    Working with PETSc options, `MatMumpsGetIcntl`

    Source code at petsc4py/PETSc/Mat.pyx:5506

    Parameters:

      icntl (int)

    Return type:

      int

  getMumpsInfo(icntl)

    Return the MUMPS parameter, `INFO[icntl]`.

    Logically collective.

    Parameters:

      icntl (int) – The index of the MUMPS INFO array.

    Return type:

      int

    See also

    `MatMumpsGetInfo`

    Source code at petsc4py/PETSc/Mat.pyx:5557

  getMumpsInfog(icntl)

    Return the MUMPS parameter, `INFOG[icntl]`.

    Logically collective.

    Parameters:

      icntl (int) – The index of the MUMPS INFOG array.

    Return type:

      int

    See also

    `MatMumpsGetInfog`

    Source code at petsc4py/PETSc/Mat.pyx:5577

  getMumpsRinfo(icntl)

    Return the MUMPS parameter, `RINFO[icntl]`.

    Logically collective.

    Parameters:

      icntl (int) – The index of the MUMPS RINFO array.

    Return type:

      float

    See also

    `MatMumpsGetRinfo`

    Source code at petsc4py/PETSc/Mat.pyx:5597

  getMumpsRinfog(icntl)

    Return the MUMPS parameter, `RINFOG[icntl]`.

    Logically collective.

    Parameters:

      icntl (int) – The index of the MUMPS RINFOG array.

    Return type:

      float

    See also

    `MatMumpsGetRinfog`

    Source code at petsc4py/PETSc/Mat.pyx:5617

  getNearNullSpace()

    Return the near-nullspace.

    Not collective.

    See also

    `getNullSpace`, `setNearNullSpace`, `MatSetNearNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3933

    Return type:

      NullSpace

  getNestISs()

    Return the index sets representing the row and column spaces.

    Not collective.

    See also

    `MatNestGetISs`

    Source code at petsc4py/PETSc/Mat.pyx:6011

    Return type:

      tuple[list[IS], list[IS]]

  getNestLocalISs()

    Return the local index sets representing the row and column spaces.

    Not collective.

    See also

    `MatNestGetLocalISs`

    Source code at petsc4py/PETSc/Mat.pyx:6032

    Return type:

      tuple[list[IS], list[IS]]

  getNestSize()

    Return the number of rows and columns of the matrix.

    Not collective.

    See also

    `MatNestGetSize`

    Source code at petsc4py/PETSc/Mat.pyx:5997

    Return type:

      tuple[int, int]

  getNestSubMatrix(i, j)

    Return a single submatrix.

    Not collective.

    Parameters:

      - i (int) – The first index of the matrix within the nesting.

      - j (int) – The second index of the matrix within the nesting.

    Return type:

      Mat

    See also

    `MatNestGetSubMat`

    Source code at petsc4py/PETSc/Mat.pyx:6053

  getNullSpace()

    Return the nullspace.

    Not collective.

    See also

    `setNullSpace`, `MatGetNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3879

    Return type:

      NullSpace

  getOption(option)

    Return the option value.

    Not collective.

    See also

    `setOption`, `MatGetOption`

    Source code at petsc4py/PETSc/Mat.pyx:2011

    Parameters:

      option (Option)

    Return type:

      bool

  getOptionsPrefix()

    Return the prefix used for searching for options in the database.

    Not collective.

    See also

    Working with PETSc options, `setOptionsPrefix`, `MatGetOptionsPrefix`

    Source code at petsc4py/PETSc/Mat.pyx:1946

    Return type:

      str

  getOrdering(ord_type)

    Return a reordering for a matrix to improve a LU factorization.

    Collective.

    Parameters:

      ord_type (OrderingType) – The type of reordering.

    Returns:

      - rp (`IS`) – The row permutation indices.

      - cp (`IS`) – The column permutation indices.

    Return type:

      tuple[IS, IS]

    See also

    `MatGetOrdering`

    Source code at petsc4py/PETSc/Mat.pyx:4803

  getOwnershipIS()

    Return the ranges of rows and columns owned by each process as index sets.

    Not collective.

    See also

    `getOwnershipRanges`, `getOwnershipRangesColumn`, `MatGetOwnershipIS`

    Source code at petsc4py/PETSc/Mat.pyx:2178

    Return type:

      tuple[IS, IS]

  getOwnershipRange()

    Return the locally owned range of rows.

    Not collective.

    See also

    `getOwnershipRanges`, `getOwnershipRangeColumn`, `MatGetOwnershipRange`

    Source code at petsc4py/PETSc/Mat.pyx:2111

    Return type:

      tuple[int, int]

  getOwnershipRangeColumn()

    Return the locally owned range of columns.

    Not collective.

    See also

    `getOwnershipRangesColumn`, `getOwnershipRange`, `MatGetOwnershipRangeColumn`

    Source code at petsc4py/PETSc/Mat.pyx:2145

    Return type:

      tuple[int, int]

  getOwnershipRanges()

    Return the range of rows owned by each process.

    Not collective.

    The returned array is the result of exclusive scan of the local sizes.

    See also

    `getOwnershipRange`, `MatGetOwnershipRanges`

    Source code at petsc4py/PETSc/Mat.pyx:2125

    Return type:

      ArrayInt

  getOwnershipRangesColumn()

    Return the range of columns owned by each process.

    Not collective.

    See also

    `getOwnershipRangeColumn`, `MatGetOwnershipRangesColumn`

    Source code at petsc4py/PETSc/Mat.pyx:2160

    Return type:

      ArrayInt

  getPythonContext()

    Return the instance of the class implementing the required Python methods.

    Not collective.

    See also

    PETSc Python matrix type, `setPythonContext`

    Source code at petsc4py/PETSc/Mat.pyx:1880

    Return type:

      Any

  getPythonType()

    Return the fully qualified Python name of the class used by the matrix.

    Not collective.

    See also

    PETSc Python matrix type, `setPythonContext`, `setPythonType`, `MatPythonGetType`

    Source code at petsc4py/PETSc/Mat.pyx:1915

    Return type:

      str

  getRedundantMatrix(nsubcomm, subcomm=None, out=None)

    Return redundant matrices on subcommunicators.

    Collective.

    Parameters:

      - nsubcomm (int) – The number of subcommunicators.

      - subcomm (Comm | None) – Communicator split or `None` for the null communicator.

      - out (Mat | None) – Optional resultant matrix. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

    Return type:

      Mat

    See also

    `MatCreateRedundantMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:3730

  getRow(row)

    Return the column indices and values for the requested row.

    Not collective.

    See also

    `MatGetRow`

    Source code at petsc4py/PETSc/Mat.pyx:2693

    Parameters:

      row (int)

    Return type:

      tuple[ArrayInt, ArrayScalar]

  getRowIJ(symmetric=False, compressed=False)

    Return the CSR representation of the local sparsity pattern.

    Collective.

    Parameters:

      - symmetric (bool) – If `True`, return the symmetrized graph.

      - compressed (bool) – If `True`, return the compressed graph.

    Return type:

      tuple[ArrayInt, ArrayInt]

    See also

    `MatGetRowIJ`

    Source code at petsc4py/PETSc/Mat.pyx:2713

  getRowSum(result=None)

    Return the row-sum vector.

    Collective.

    Parameters:

      result (Vec | None) – Optional vector to store the result.

    Return type:

      Vec

    See also

    `MatGetRowSum`

    Source code at petsc4py/PETSc/Mat.pyx:3782

  getSchurComplementSubMatrices()

    Return Schur complement sub-matrices.

    Collective.

    See also

    `MatSchurComplementGetSubMatrices`

    Source code at petsc4py/PETSc/Mat.pyx:4250

    Return type:

      tuple[Mat, Mat, Mat, Mat, Mat]

  getSize()

    Return the global number of rows and columns.

    Not collective.

    See also

    `getLocalSize`, `getSizes`, `MatGetSize`

    Source code at petsc4py/PETSc/Mat.pyx:2039

    Return type:

      tuple[int, int]

  getSizes()

    Return the tuple of matrix layouts.

    Not collective.

    See also

    `getLocalSize`, `getSize`

    Source code at petsc4py/PETSc/Mat.pyx:2067

    Return type:

      tuple[LayoutSizeSpec, LayoutSizeSpec]

  getTransposeMat()

    Return the internal matrix of a `Type.TRANSPOSE` matrix.

    Not collective.

    Parameters:

      mat – Matrix A of type `Type.TRANSPOSE`.

    Return type:

      Mat

    See also

    `MatTransposeGetMat`

    Source code at petsc4py/PETSc/Mat.pyx:1330

  getTransposeNullSpace()

    Return the transpose nullspace.

    Not collective.

    See also

    `getNullSpace`, `setTransposeNullSpace`, `MatGetTransposeNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3906

    Return type:

      NullSpace

  getType()

    Return the type of the matrix.

    Not collective.

    See also

    `setType`, `Type`, `MatGetType`

    Source code at petsc4py/PETSc/Mat.pyx:2025

    Return type:

      str

  getValue(row, col)

    Return the value in the (row, col) position.

    Not collective.

    See also

    `MatGetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2618

    Return type:

      Scalar

  getValues(rows, cols, values=None)

    Return the values in the `zip(rows, cols)` positions.

    Not collective.

    Parameters:

      - rows (Sequence[int]) – Row indices.

      - cols (Sequence[int]) – Column indices.

      - values (ArrayScalar | None) – Optional array where to store the values.

    Return type:

      ArrayScalar

    See also

    `MatGetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2634

  getValuesCSR()

    Return the CSR representation of the local part of the matrix.

    Not collective.

    See also

    `MatGetRow`

    Source code at petsc4py/PETSc/Mat.pyx:2655

    Return type:

      tuple[ArrayInt, ArrayInt, ArrayScalar]

  getVecType()

    Return the vector type used by the matrix.

    Not collective.

    See also

    `setVecType`, `MatGetVecType`

    Source code at petsc4py/PETSc/Mat.pyx:686

    Return type:

      str

  hermitianTranspose(out=None)

    Return the transposed Hermitian matrix.

    Collective.

    Parameters:

      out (Mat | None) – Optional return matrix. If `None`, inplace transposition is performed. Otherwise, the matrix is reused.

    Return type:

      Mat

    See also

    `MatHermitianTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:2349

  imagPart(out=None)

    Return the imaginary part of the matrix.

    Collective.

    Parameters:

      out (Mat | None) – Optional return matrix. If `None`, the operation is performed in-place. Otherwise, the operation is performed on `out`.

    Return type:

      Mat

    See also

    `realPart`, `conjugate`, `MatImaginaryPart`

    Source code at petsc4py/PETSc/Mat.pyx:2399

  increaseOverlap(iset, overlap=1)

    Increase the overlap of a index set.

    Collective.

    See also

    `MatIncreaseOverlap`

    Source code at petsc4py/PETSc/Mat.pyx:4116

    Parameters:

      - iset (IS)

      - overlap (int)

    Return type:

      None

  invertBlockDiagonal()

    Return the inverse of the block-diagonal entries.

    Collective.

    See also

    `MatInvertBlockDiagonal`

    Source code at petsc4py/PETSc/Mat.pyx:3846

    Return type:

      ArrayScalar

  isAssembled()

    The boolean flag indicating if the matrix is assembled.

    Not collective.

    See also

    `assemble`, `MatAssembled`

    Source code at petsc4py/PETSc/Mat.pyx:3604

    Return type:

      bool

  isHermitian(tol=0)

    Return the boolean indicating if the matrix is Hermitian.

    Collective.

    Parameters:

      tol (float) – Tolerance for comparison.

    Return type:

      bool

    See also

    `MatIsHermitian`

    Source code at petsc4py/PETSc/Mat.pyx:2538

  isHermitianKnown()

    Return the 2-tuple indicating if the matrix is known to be Hermitian.

    Not collective.

    See also

    `MatIsHermitianKnown`

    Source code at petsc4py/PETSc/Mat.pyx:2558

    Return type:

      tuple[bool, bool]

  isLinear(n=1)

    Return whether the Mat is a linear operator.

    Collective.

    Parameters:

      n (int) – Number of random vectors to be tested.

    Return type:

      bool

    See also

    `MatIsLinear`

    Source code at petsc4py/PETSc/Mat.pyx:2587

  isStructurallySymmetric()

    Return the boolean indicating if the matrix is structurally symmetric.

    Not collective.

    See also

    `MatIsStructurallySymmetric`

    Source code at petsc4py/PETSc/Mat.pyx:2573

    Return type:

      bool

  isSymmetric(tol=0)

    Return the boolean indicating if the matrix is symmetric.

    Collective.

    Parameters:

      tol (float) – Tolerance for comparison.

    Return type:

      bool

    See also

    `MatIsSymmetric`

    Source code at petsc4py/PETSc/Mat.pyx:2503

  isSymmetricKnown()

    Return the 2-tuple indicating if the matrix is known to be symmetric.

    Not collective.

    See also

    `MatIsSymmetricKnown`

    Source code at petsc4py/PETSc/Mat.pyx:2523

    Return type:

      tuple[bool, bool]

  isTranspose(mat=None, tol=0)

    Return the result of matrix comparison with transposition.

    Collective.

    Parameters:

      - mat (Mat | None) – Matrix to compare against. Uses `self` if `None`.

      - tol (float) – Tolerance for comparison.

    Return type:

      bool

    See also

    `MatIsTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:2480

  kron(mat, result=None)

    Compute C, the Kronecker product of A and B.

    Collective.

    Parameters:

      - mat (Mat) – The right hand matrix B.

      - result (Mat | None) – The optional resultant matrix. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When it is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

    Returns:

      result – The resultant matrix C, the Kronecker product of A and B.

    Return type:

      `Mat`

    See also

    `MatSeqAIJKron`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4732

  load(viewer)

    Load a matrix.

    Collective.

    See also

    `MatLoad`

    Source code at petsc4py/PETSc/Mat.pyx:2260

    Parameters:

      viewer (Viewer)

    Return type:

      Self

  matMatMult(B, C, result=None, fill=None)

    Perform matrix-matrix-matrix multiplication D=ABC.

    Neighborwise collective.

    Parameters:

      - B (Mat) – The middle matrix B.

      - C (Mat) – The right hand matrix C.

      - result (Mat | None) – The optional resultant matrix D. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When D is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix D.

    Return type:

      `Mat`

    See also

    `MatMatMatMult`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4687

  matMult(mat, result=None, fill=None)

    Perform matrix-matrix multiplication C=AB.

    Neighborwise collective.

    Parameters:

      - mat (Mat) – The right hand matrix B.

      - result (Mat | None) – The optional resultant matrix C. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When C is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix C.

    Return type:

      `Mat`

    Notes

    To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

    See also

    `MatMatMult`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4448

  matSolve(B, X)

    Solve AX=B, given a factored matrix A.

    Neighborwise collective.

    Parameters:

      - B (Mat) – The right-hand side matrix of type `Type.DENSE`. Can be of type `Type.AIJ` if using MUMPS.

      - X (Mat) – The output solution matrix, must be different than `B`.

    Return type:

      None

    See also

    `KSP.create`, `MatMatSolve`

    Source code at petsc4py/PETSc/Mat.pyx:5767

  matTransposeMult(mat, result=None, fill=None)

    Perform matrix-matrix multiplication C=ABᵀ.

    Neighborwise collective.

    Parameters:

      - mat (Mat) – The right hand matrix B.

      - result (Mat | None) – The optional resultant matrix C. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When C is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix C.

    Return type:

      `Mat`

    Notes

    To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

    See also

    `MatMatTransposeMult`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4495

  mult(x, y)

    Perform the matrix vector product y = A @ x.

    Collective.

    Parameters:

      - x (Vec) – The input vector.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMult`

    Source code at petsc4py/PETSc/Mat.pyx:3950

  multAdd(x, v, y)

    Perform the matrix vector product with addition y = A @ x + v.

    Collective.

    Parameters:

      - x (Vec) – The input vector for the matrix-vector product.

      - v (Vec) – The input vector to be added to.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMultAdd`

    Source code at petsc4py/PETSc/Mat.pyx:3969

  multHermitian(x, y)

    Perform the Hermitian matrix vector product y = A^H @ x.

    Collective.

    Parameters:

      - x (Vec) – The input vector for the Hermitian matrix-vector product.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMultHermitianTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:4030

  multHermitianAdd(x, v, y)

    Perform the Hermitian matrix vector product with addition y = A^H @ x + v.

    Collective.

    Parameters:

      - x (Vec) – The input vector for the Hermitian matrix-vector product.

      - v (Vec) – The input vector to be added to.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMultHermitianTransposeAdd`

    Source code at petsc4py/PETSc/Mat.pyx:4049

  multTranspose(x, y)

    Perform the transposed matrix vector product y = A^T @ x.

    Collective.

    Parameters:

      - x (Vec) – The input vector.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMultTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:3990

  multTransposeAdd(x, v, y)

    Perform the transposed matrix vector product with addition y = A^T @ x + v.

    Collective.

    Parameters:

      - x (Vec) – The input vector for the transposed matrix-vector product.

      - v (Vec) – The input vector to be added to.

      - y (Vec) – The output vector.

    Return type:

      None

    See also

    `MatMultTransposeAdd`

    Source code at petsc4py/PETSc/Mat.pyx:4009

  norm(norm_type=None)

    Compute the requested matrix norm.

    Collective.

    A 2-tuple is returned if `NormType.NORM_1_AND_2` is specified.

    See also

    `MatNorm`, `NormType`

    Source code at petsc4py/PETSc/Mat.pyx:4320

    Parameters:

      norm_type (NormTypeSpec)

    Return type:

      float | tuple[float, float]

  permute(row, col)

    Return the permuted matrix.

    Collective.

    Parameters:

      - row (IS) – Row permutation.

      - col (IS) – Column permutation.

    Return type:

      Mat

    See also

    `MatPermute`

    Source code at petsc4py/PETSc/Mat.pyx:2445

  preallocatorPreallocate(A, fill=True)

    Preallocate memory for a matrix using a preallocator matrix.

    Collective.

    The current matrix (`self`) must be of type `Type.PREALLOCATOR`.

    Parameters:

      - A (Mat) – The matrix to be preallocated.

      - fill (bool) – Flag indicating whether or not to insert zeros into the newly allocated matrix, defaults to `True`.

    Return type:

      None

    See also

    `MatPreallocatorPreallocate`

    Source code at petsc4py/PETSc/Mat.pyx:1025

  ptap(P, result=None, fill=None)

    Creates the matrix product C = PᵀAP.

    Neighborwise collective.

    Parameters:

      - P (Mat) – The matrix P.

      - result (Mat | None) – The optional resultant matrix C. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When C is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix C.

    Return type:

      `Mat`

    Notes

    To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

    An alternative approach to this function is to use `MatProductCreate` and set the desired options before the computation is done.

    See also

    `MatPtAP`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4589

  rart(R, result=None, fill=None)

    Create the matrix product C = RARᵀ.

    Neighborwise collective.

    Parameters:

      - R (Mat) – The projection matrix.

      - result (Mat | None) – The optional resultant matrix C. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When C is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/nnz(A), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix C.

    Return type:

      `Mat`

    Notes

    To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

    See also

    `MatRARt`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4640

  realPart(out=None)

    Return the real part of the matrix.

    Collective.

    Parameters:

      out (Mat | None) – Optional return matrix. If `None`, the operation is performed in-place. Otherwise, the operation is performed on `out`.

    Return type:

      Mat

    See also

    `imagPart`, `conjugate`, `MatRealPart`

    Source code at petsc4py/PETSc/Mat.pyx:2376

  reorderForNonzeroDiagonal(isrow, iscol, atol=0)

    Change a matrix ordering to remove zeros from the diagonal.

    Collective.

    Parameters:

      - isrow (IS) – The row reordering.

      - iscol (IS) – The column reordering.

      - atol (float) – The absolute tolerance. Values along the diagonal whose absolute value are smaller than this tolerance are moved off the diagonal.

    Return type:

      None

    See also

    `getOrdering`, `MatReorderForNonzeroDiagonal`

    Source code at petsc4py/PETSc/Mat.pyx:4831

  resetLMVM(destructive=False)

    Flushes all of the accumulated updates out of the LMVM matrix.

    Logically collective.

    Parameters:

      destructive (bool) – Flag for enabling destruction of data structures.

    Return type:

      None

    See also

    `MatLMVMReset`

    Source code at petsc4py/PETSc/Mat.pyx:5466

  restoreDenseColumnVec(i, mode='rw', V=None)

    Restore the iᵗʰ column vector of the dense matrix.

    Collective.

    Parameters:

      - i (int) – The column index to be restored.

      - mode (AccessModeSpec) – The access type of the vector to be restored.

      - V (Vec | None) – The vector obtained from calling `getDenseColumnVec`.

    Return type:

      None

    See also

    `getDenseColumnVec`, `MatDenseRestoreColumnVec`, `MatDenseRestoreColumnVecRead`, `MatDenseRestoreColumnVecWrite`

    Source code at petsc4py/PETSc/Mat.pyx:5962

  restoreDenseSubMatrix(mat)

    Restore access to a submatrix of a `Type.DENSE` matrix.

    Collective.

    Parameters:

      mat (Mat) – the matrix obtained from `getDenseSubMatrix`.

    Return type:

      None

    See also

    `getDenseSubMatrix`, `MatDenseRestoreSubMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:5911

  restoreISLocalMat(local)

    Restore the local matrix obtained with `getISLocalMat`.

    Not collective.

    Parameters:

      local (Mat) – The local matrix.

    Return type:

      None

    See also

    `MatISRestoreLocalMat`

    Source code at petsc4py/PETSc/Mat.pyx:5098

  restoreLocalSubMatrix(isrow, iscol, submat)

    Restore a reference to a submatrix obtained with `getLocalSubMatrix`.

    Collective.

    Parameters:

      - isrow (IS) – Row index set.

      - iscol (IS) – Column index set.

      - submat (Mat) – The submatrix.

    Return type:

      None

    See also

    `getLocalSubMatrix`, `MatRestoreLocalSubMatrix`

    Source code at petsc4py/PETSc/Mat.pyx:4297

  retrieveValues()

    Retrieve a copy of the matrix values previously stored with `storeValues`.

    Collective.

    See also

    `storeValues`, `MatRetrieveValues`

    Source code at petsc4py/PETSc/Mat.pyx:3537

    Return type:

      None

  scale(alpha)

    Scale the matrix.

    Collective.

    See also

    `MatScale`

    Source code at petsc4py/PETSc/Mat.pyx:4342

    Parameters:

      alpha (Scalar)

    Return type:

      None

  setBlockSize(bsize)

    Set the matrix block size (same for rows and columns).

    Logically collective.

    Parameters:

      bsize (int) – Block size.

    Return type:

      None

    See also

    `setBlockSizes`, `setSizes`, `MatSetBlockSize`

    Source code at petsc4py/PETSc/Mat.pyx:614

  setBlockSizes(row_bsize, col_bsize)

    Set the row and column block sizes.

    Logically collective.

    Parameters:

      - row_bsize (int) – Row block size.

      - col_bsize (int) – Column block size.

    Return type:

      None

    See also

    `setBlockSize`, `setSizes`, `MatSetBlockSizes`

    Source code at petsc4py/PETSc/Mat.pyx:632

  setDM(dm)

    Set the DM defining the data layout of the matrix.

    Not collective.

    Parameters:

      dm (DM) – The `DM`.

    Return type:

      None

    See also

    `MatSetDM`

    Source code at petsc4py/PETSc/Mat.pyx:6096

  setDenseLDA(lda)

    Set the leading dimension of the array used by the dense matrix.

    Not collective.

    Parameters:

      lda (int) – The leading dimension.

    Return type:

      None

    See also

    `MatDenseSetLDA`

    Source code at petsc4py/PETSc/Mat.pyx:5789

  setDiagonal(diag, addv=None)

    Set the diagonal values of the matrix.

    Collective.

    Parameters:

      - diag (Vec) – Vector storing diagonal values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `getDiagonal`, `MatDiagonalSet`

    Source code at petsc4py/PETSc/Mat.pyx:3804

  setFromOptions()

    Configure the matrix from the options database.

    Collective.

    See also

    Working with PETSc options, `MatSetFromOptions`

    Source code at petsc4py/PETSc/Mat.pyx:1974

    Return type:

      None

  setISAllowRepeated(allow=True)

    Allow repeated entries in the local to global map.

    Logically collective.

    Parameters:

      allow (bool) – When `True`, local dofs are allowed to map to the same global dof.

    Return type:

      None

    See also

    `getISAllowRepeated`, `MatISSetAllowRepeated`

    Source code at petsc4py/PETSc/Mat.pyx:5032

  setISLocalMat(local)

    Set the local matrix stored inside a `Type.IS`.

    Not collective.

    Parameters:

      local (Mat) – The local matrix.

    Return type:

      None

    See also

    `MatISSetLocalMat`

    Source code at petsc4py/PETSc/Mat.pyx:5115

  setISPreallocation(nnz, onnz)

    Preallocate memory for a `Type.IS` parallel matrix.

    Collective.

    Parameters:

      - nnz (Sequence[int]) – The sequence whose length corresponds to the number of local rows and values which represent the number of nonzeros in the various rows of the diagonal of the local submatrix.

      - onnz (Sequence[int]) – The sequence whose length corresponds to the number of local rows and values which represent the number of nonzeros in the various rows of the off-diagonal of the local submatrix.

    Return type:

      Self

    See also

    `MatISSetPreallocation`

    Source code at petsc4py/PETSc/Mat.pyx:5132

  setLGMap(rmap, cmap=None)

    Set the local-to-global mappings.

    Collective.

    Parameters:

      - rmap (LGMap) – Row mapping.

      - cmap (LGMap | None) – Column mapping. If `None`, `cmap = rmap`.

    Return type:

      None

    See also

    `getLGMap`, `MatSetLocalToGlobalMapping`

    Source code at petsc4py/PETSc/Mat.pyx:3011

  setLMVMJ0(J0)

    Set the initial Jacobian of the LMVM matrix.

    Logically collective.

    Parameters:

      J0 (Mat) – The initial Jacobian matrix.

    Return type:

      None

    See also

    `getLMVMJ0`, `MatLMVMSetJ0`

    Source code at petsc4py/PETSc/Mat.pyx:5378

  setLMVMJ0KSP(ksp)

    Set the KSP of the LMVM matrix.

    Logically collective.

    Parameters:

      ksp (KSP) – The KSP.

    Return type:

      None

    See also

    `getLMVMJ0KSP`, `MatLMVMSetJ0KSP`

    Source code at petsc4py/PETSc/Mat.pyx:5409

  setLRCMats(A, U, c=None, V=None)

    Set the constituents of a `Type.LRC` matrix.

    Logically collective.

    Parameters:

      - A (`Mat`) – The `A` matrix, or `None` to omit `A`.

      - U (`Mat`) – The first dense rectangular matrix.

      - c (`Vec`) – The sequential vector containing the diagonal of `C`, or `None` for all ones.

      - V (`Mat`) – The second dense rectangular matrix, or `None` for a copy of `U`.

    Return type:

      None

    See also

    `MatLRCSetMats`

    Source code at petsc4py/PETSc/Mat.pyx:5197

  setMumpsCntl(icntl, val)

    Set a MUMPS parameter, `CNTL[icntl] = val`.

    Logically collective.

    Parameters:

      - icntl (int) – The index of the MUMPS parameter array.

      - val (float) – The value to set.

    Return type:

      None

    See also

    Working with PETSc options, `MatMumpsSetCntl`

    Source code at petsc4py/PETSc/Mat.pyx:5521

  setMumpsIcntl(icntl, ival)

    Set a MUMPS parameter, `ICNTL[icntl] = ival`.

    Logically collective.

    Parameters:

      - icntl (int) – The index of the MUMPS parameter array.

      - ival (int) – The value to set.

    Return type:

      None

    See also

    Working with PETSc options, `MatMumpsSetIcntl`

    Source code at petsc4py/PETSc/Mat.pyx:5485

  setNearNullSpace(nsp)

    Set the near-nullspace.

    Collective.

    See also

    `setNullSpace`, `getNearNullSpace`, `MatSetNearNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3921

    Parameters:

      nsp (NullSpace)

    Return type:

      None

  setNestVecType(vec_type)

    Set the vector type for a `Type.NEST` matrix.

    Collective.

    Parameters:

      vec_type (Type | str) – Vector type used when creating vectors with `createVecs`.

    Return type:

      None

    See also

    `getVecType`, `MatNestSetVecType`

    Source code at petsc4py/PETSc/Mat.pyx:700

  setNullSpace(nsp)

    Set the nullspace.

    Collective.

    See also

    `getNullSpace`, `MatSetNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3867

    Parameters:

      nsp (NullSpace)

    Return type:

      None

  setOption(option, flag)

    Set option.

    Collective.

    See also

    `getOption`, `MatSetOption`

    Source code at petsc4py/PETSc/Mat.pyx:1999

    Parameters:

      - option (Option)

      - flag (bool)

    Return type:

      None

  setOptionsPrefix(prefix=None)

    Set the prefix used for searching for options in the database.

    Logically collective.

    See also

    Working with PETSc options, `getOptionsPrefix`, `MatSetOptionsPrefix`

    Source code at petsc4py/PETSc/Mat.pyx:1932

    Parameters:

      prefix (str | None)

    Return type:

      None

  setPreallocationCOO(coo_i, coo_j)

    Set preallocation using coordinate format with global indices.

    Collective.

    Parameters:

      - coo_i (Sequence[int]) – Row indices in COO format.

      - coo_j (Sequence[int]) – Column indices in COO format.

    Return type:

      Self

    See also

    `setValuesCOO`, `setPreallocationNNZ`, `setPreallocationCSR`, `MatSetPreallocationCOO`

    Source code at petsc4py/PETSc/Mat.pyx:927

  setPreallocationCOOLocal(coo_i, coo_j)

    Set preallocation using coordinate format with local indices.

    Collective.

    Parameters:

      - coo_i (Sequence[int]) – Row indices in COO format.

      - coo_j (Sequence[int]) – Column indices in COO format.

    Return type:

      Self

    See also

    `setPreallocationCOO`, `setValuesCOO`, `setLGMap`, `MatSetPreallocationCOOLocal`, `MatSetPreallocationCOOLocal`

    Source code at petsc4py/PETSc/Mat.pyx:959

  setPreallocationCSR(csr)

    Preallocate memory for the matrix with a CSR layout.

    Collective.

    Correct preallocation can result in a dramatic reduction in matrix assembly time.

    Parameters:

      csr (CSRSpec | CSRIndicesSpec) – Local matrix data in compressed sparse row layout format.

    Return type:

      Self

    Notes

    Must use the block-compressed form with `Type.BAIJ` and `Type.SBAIJ`.

    See also

    `setPreallocationNNZ`, `createAIJ`, `createBAIJ`, `createSBAIJ`, `MatSeqAIJSetPreallocationCSR`, `MatMPIAIJSetPreallocationCSR`, `MatSeqBAIJSetPreallocationCSR`, `MatMPIBAIJSetPreallocationCSR`, `MatSeqSBAIJSetPreallocationCSR`, `MatMPISBAIJSetPreallocationCSR`

    Source code at petsc4py/PETSc/Mat.pyx:991

  setPreallocationDense(array)

    Set the array used for storing matrix elements for a dense matrix.

    Collective.

    Parameters:

      array (Sequence[Scalar]) – Array that will be used to store matrix data.

    Return type:

      Self

    See also

    `MatSeqDenseSetPreallocation`, `MatMPIDenseSetPreallocation`

    Source code at petsc4py/PETSc/Mat.pyx:1232

  setPreallocationNNZ(nnz)

    Preallocate memory for the matrix with a non-zero pattern.

    Collective.

    Correct preallocation can result in a dramatic reduction in matrix assembly time.

    Parameters:

      nnz (NNZSpec) – The number of non-zeros per row for the local portion of the matrix, or a 2-tuple for the on-process and off-process part of the matrix.

    Return type:

      Self

    See also

    `setPreallocationCSR`, `createAIJ`, `MatSeqAIJSetPreallocation`, `MatMPIAIJSetPreallocation`

    Source code at petsc4py/PETSc/Mat.pyx:901

  setPythonContext(context)

    Set the instance of the class implementing the required Python methods.

    Logically collective.

    Notes

    In order to use the matrix, `Mat.setUp` must be called after having set the context. Pass `None` to reset the matrix to its initial state.

    See also

    PETSc Python matrix type, `getPythonContext`, `setPythonType`

    Source code at petsc4py/PETSc/Mat.pyx:1863

    Parameters:

      context (Any)

    Return type:

      None

  setPythonType(py_type)

    Set the fully qualified Python name of the class to be used.

    Collective.

    Notes

    In order to use the matrix, `Mat.setUp` must be called after having set the type.

    See also

    PETSc Python matrix type, `setPythonContext`, `getPythonType`, `MatPythonSetType`

    Source code at petsc4py/PETSc/Mat.pyx:1895

    Parameters:

      py_type (str)

    Return type:

      None

  setRandom(random=None)

    Set random values in the matrix.

    Collective.

    Parameters:

      random (Random | None) – The random number generator object or `None` for the default.

    Return type:

      None

    See also

    `MatSetRandom`

    Source code at petsc4py/PETSc/Mat.pyx:4381

  setSizes(size, bsize=None)

    Set the local, global and block sizes.

    Collective.

    Parameters:

      - size (MatSizeSpec) – Matrix size.

      - bsize (MatBlockSizeSpec | None) – Matrix block size. If `None`, a block size of `1` is set.

    Return type:

      None

    Examples

    Create a `Mat` with `n` rows and columns and the same local and global sizes.

        >>> mat = PETSc.Mat().create()
        >>> mat.setFromOptions()
        >>> mat.setSizes(n)

    Create a `Mat` with `nr` rows, `nc` columns and the same local and global sizes.

        >>> mat = PETSc.Mat().create()
        >>> mat.setFromOptions()
        >>> mat.setSizes([nr, nc])

    Create a `Mat` with `nrl` local rows, `nrg` global rows, `ncl` local columns and `ncg` global columns.

        >>> mat = PETSc.Mat().create()
        >>> mat.setFromOptions()
        >>> mat.setSizes([[nrl, nrg], [ncl, ncg]])

    See also

    `setBlockSize`, `setBlockSizes`, `MatSetSizes`, `MatSetBlockSize`, `MatSetBlockSizes`

    Source code at petsc4py/PETSc/Mat.pyx:561

  setStencil(dims, starts=None, dof=1)

    Set matrix stencil.

    Not collective.

    See also

    `MatSetStencil`

    Source code at petsc4py/PETSc/Mat.pyx:3269

    Parameters:

      - dims (DimsSpec)

      - starts (DimsSpec | None)

      - dof (int)

    Return type:

      None

  setTransposeNullSpace(nsp)

    Set the transpose nullspace.

    Collective.

    See also

    `setNullSpace`, `getTransposeNullSpace`, `MatSetTransposeNullSpace`

    Source code at petsc4py/PETSc/Mat.pyx:3894

    Parameters:

      nsp (NullSpace)

    Return type:

      None

  setTransposePrecursor(out)

    Set transpose precursor.

    Logically collective.

    See also

    `MatTransposeSetPrecursor`

    Source code at petsc4py/PETSc/Mat.pyx:2337

    Parameters:

      out (Mat)

    Return type:

      None

  setType(mat_type)

    Set the matrix type.

    Collective.

    Parameters:

      mat_type (Type | str) – The matrix type.

    Return type:

      None

    See also

    `create`, `getType`, `MatSetType`

    Source code at petsc4py/PETSc/Mat.pyx:542

  setUnfactored()

    Set a factored matrix to be treated as unfactored.

    Logically collective.

    See also

    `MatSetUnfactored`

    Source code at petsc4py/PETSc/Mat.pyx:5018

    Return type:

      None

  setUp()

    Set up the internal data structures for using the matrix.

    Collective.

    See also

    `MatSetUp`

    Source code at petsc4py/PETSc/Mat.pyx:1986

    Return type:

      Self

  setValue(row, col, value, addv=None)

    Set a value to the `(row, col)` entry of the matrix.

    Not collective.

    Parameters:

      - row (int) – Row index.

      - col (int) – Column index.

      - value (Scalar) – The scalar value.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2774

  setValueBlockedStagStencil(row, col, value, addv=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:3353

    Return type:

      None

  setValueBlockedStencil(row, col, value, addv=None)

    Set a block of values to row and col stencil.

    Not collective.

    Parameters:

      - row (Stencil) – Row stencil.

      - col (Stencil) – Column stencil.

      - value (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesBlockedStencil`

    Source code at petsc4py/PETSc/Mat.pyx:3323

  setValueLocal(row, col, value, addv=None)

    Set a value to the `(row, col)` entry of the matrix in local ordering.

    Not collective.

    Parameters:

      - row (int) – Local row index.

      - col (int) – Local column index.

      - value (Scalar) – The scalar value.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3048

  setValueStagStencil(row, col, value, addv=None)

    Not implemented.

    Source code at petsc4py/PETSc/Mat.pyx:3319

    Return type:

      None

  setValueStencil(row, col, value, addv=None)

    Set a value to row and col stencil.

    Not collective.

    Parameters:

      - row (Stencil) – Row stencil.

      - col (Stencil) – Column stencil.

      - value (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesStencil`

    Source code at petsc4py/PETSc/Mat.pyx:3289

  setValues(rows, cols, values, addv=None)

    Set values to the rows ⊗ cols entries of the matrix.

    Not collective.

    Parameters:

      - rows (Sequence[int]) – Row indices.

      - cols (Sequence[int]) – Column indices.

      - values (Sequence[Scalar]) – The scalar values. A sequence of length at least `len(rows) * len(cols)`.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2806

  setValuesBlocked(rows, cols, values, addv=None)

    Set values to the rows ⊗ col block entries of the matrix.

    Not collective.

    Parameters:

      - rows (Sequence[int]) – Block row indices.

      - cols (Sequence[int]) – Block column indices.

      - values (Sequence[Scalar]) – The scalar values. A sequence of length at least `len(rows) * len(cols) * bs * bs`, where `bs` is the block size of the matrix.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesBlocked`

    Source code at petsc4py/PETSc/Mat.pyx:2918

  setValuesBlockedCSR(I, J, V, addv=None)

    Set values stored in block CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Block row pointers.

      - J (Sequence[int]) – Block column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesBlocked`

    Source code at petsc4py/PETSc/Mat.pyx:2983

  setValuesBlockedIJV(I, J, V, addv=None, rowmap=None)

    Set a subset of values stored in block CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Block row pointers.

      - J (Sequence[int]) – Block column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

      - rowmap (Sequence[int] | None) – Optional iterable indicating which block row to insert.

    Return type:

      None

    See also

    `MatSetValuesBlocked`

    Source code at petsc4py/PETSc/Mat.pyx:2952

  setValuesBlockedLocal(rows, cols, values, addv=None)

    Set values to the rows ⊗ col block entries of the matrix in local ordering.

    Not collective.

    Parameters:

      - rows (Sequence[int]) – Local block row indices.

      - cols (Sequence[int]) – Local block column indices.

      - values (Sequence[Scalar]) – The scalar values. A sequence of length at least `len(rows) * len(cols) * bs * bs`, where `bs` is the block size of the matrix.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesBlockedLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3172

  setValuesBlockedLocalCSR(I, J, V, addv=None)

    Set values stored in block CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Block row pointers.

      - J (Sequence[int]) – Local block column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesBlockedLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3237

  setValuesBlockedLocalIJV(I, J, V, addv=None, rowmap=None)

    Set a subset of values stored in block CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Block row pointers.

      - J (Sequence[int]) – Local block column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

      - rowmap (Sequence[int] | None) – Optional iterable indicating which block row to insert.

    Return type:

      None

    See also

    `MatSetValuesBlockedLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3206

  setValuesBlockedLocalRCV(R, C, V, addv=None)

    Undocumented.

    Source code at petsc4py/PETSc/Mat.pyx:3202

    Return type:

      None

  setValuesBlockedRCV(R, C, V, addv=None)

    Undocumented.

    Source code at petsc4py/PETSc/Mat.pyx:2948

    Return type:

      None

  setValuesCOO(coo_v, addv=None)

    Set values after preallocation with coordinate format.

    Collective.

    Parameters:

      - coo_v (Sequence[Scalar]) – The matrix values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `setPreallocationCOO`, `MatSetValuesCOO`

    Source code at petsc4py/PETSc/Mat.pyx:2869

  setValuesCSR(I, J, V, addv=None)

    Set values stored in CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Row pointers.

      - J (Sequence[int]) – Column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2890

  setValuesIJV(I, J, V, addv=None, rowmap=None)

    Set a subset of values stored in CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Row pointers.

      - J (Sequence[int]) – Column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

      - rowmap (Sequence[int] | None) – Optional iterable indicating which row to insert.

    Return type:

      None

    See also

    `MatSetValues`

    Source code at petsc4py/PETSc/Mat.pyx:2838

  setValuesLocal(rows, cols, values, addv=None)

    Set values to the rows ⊗ col entries of the matrix in local ordering.

    Not collective.

    Parameters:

      - rows (Sequence[int]) – Local row indices.

      - cols (Sequence[int]) – Local column indices.

      - values (Sequence[Scalar]) – The scalar values. A sequence of length at least `len(rows) * len(cols)`.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3081

  setValuesLocalCSR(I, J, V, addv=None)

    Set values stored in CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Row pointers.

      - J (Sequence[int]) – Local column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

    Return type:

      None

    See also

    `MatSetValuesLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3144

  setValuesLocalIJV(I, J, V, addv=None, rowmap=None)

    Set a subset of values stored in CSR format.

    Not collective.

    Parameters:

      - I (Sequence[int]) – Row pointers.

      - J (Sequence[int]) – Local column indices.

      - V (Sequence[Scalar]) – The scalar values.

      - addv (InsertModeSpec) – Insertion mode.

      - rowmap (Sequence[int] | None) – Optional iterable indicating which row to insert.

    Return type:

      None

    See also

    `MatSetValuesLocal`

    Source code at petsc4py/PETSc/Mat.pyx:3113

  setValuesLocalRCV(R, C, V, addv=None)

    Undocumented.

    Source code at petsc4py/PETSc/Mat.pyx:3109

    Return type:

      None

  setValuesRCV(R, C, V, addv=None)

    Undocumented.

    Source code at petsc4py/PETSc/Mat.pyx:2834

    Return type:

      None

  setVariableBlockSizes(blocks)

    Set diagonal point-blocks of the matrix.

    Not collective.

    See also

    `setBlockSize`, `MatSetVariableBlockSizes`

    Source code at petsc4py/PETSc/Mat.pyx:653

    Parameters:

      blocks (Sequence[int])

    Return type:

      None

  setVecType(vec_type)

    Set the vector type.

    Collective.

    Parameters:

      vec_type (Type | str) – Vector type used when creating vectors with `createVecs`.

    Return type:

      None

    See also

    `getVecType`, `MatSetVecType`

    Source code at petsc4py/PETSc/Mat.pyx:667

  shift(alpha)

    Shift the matrix.

    Collective.

    See also

    `MatShift`

    Source code at petsc4py/PETSc/Mat.pyx:4355

    Parameters:

      alpha (Scalar)

    Return type:

      None

  solve(b, x)

    Solve Ax=b, given a factored matrix.

    Neighborwise collective.

    The vectors `b` and `x` cannot be the same. Most users should employ the `KSP` interface for linear solvers instead of working directly with matrix algebra routines.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - x (Vec) – The output solution vector, must be different than `b`.

    Return type:

      None

    See also

    `KSP.create`, `solveTranspose`, `MatSolve`

    Source code at petsc4py/PETSc/Mat.pyx:5677

  solveAdd(b, y, x)

    Solve x=y+A⁻¹b, given a factored matrix.

    Neighborwise collective.

    The vectors `b` and `x` cannot be the same.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - y (Vec) – The vector to be added

      - x (Vec) – The output solution vector, must be different than `b`.

    Return type:

      None

    See also

    `KSP.create`, `MatSolve`, `MatSolveAdd`

    Source code at petsc4py/PETSc/Mat.pyx:5721

  solveBackward(b, x)

    Solve Ux=b, given a factored matrix A=LU.

    Neighborwise collective.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - x (Vec) – The output solution vector.

    Return type:

      None

    See also

    `MatBackwardSolve`

    Source code at petsc4py/PETSc/Mat.pyx:5658

  solveForward(b, x)

    Solve Lx = b, given a factored matrix A = LU.

    Neighborwise collective.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - x (Vec) – The output solution vector.

    Return type:

      None

    See also

    `MatForwardSolve`

    Source code at petsc4py/PETSc/Mat.pyx:5639

  solveTranspose(b, x)

    Solve Aᵀx=b, given a factored matrix.

    Neighborwise collective.

    The vectors `b` and `x` cannot be the same.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - x (Vec) – The output solution vector, must be different than `b`.

    Return type:

      None

    See also

    `KSP.create`, `MatSolve`, `MatSolveTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:5700

  solveTransposeAdd(b, y, x)

    Solve x=y+A⁻ᵀb, given a factored matrix.

    Neighborwise collective.

    The vectors `b` and `x` cannot be the same.

    Parameters:

      - b (Vec) – The right-hand side vector.

      - y (Vec) – The vector to be added

      - x (Vec) – The output solution vector, must be different than `b`.

    Return type:

      None

    See also

    `KSP.create`, `MatSolve`, `MatSolveTransposeAdd`

    Source code at petsc4py/PETSc/Mat.pyx:5744

  storeValues()

    Stash a copy of the matrix values.

    Collective.

    See also

    `retrieveValues`, `MatStoreValues`

    Source code at petsc4py/PETSc/Mat.pyx:3525

    Return type:

      None

  toDLPack(mode='rw')

    Return a DLPack `PyCapsule` wrapping the vector data.

    Source code at petsc4py/PETSc/Mat.pyx:6184

    Parameters:

      mode (AccessModeSpec)

    Return type:

      Any

  transpose(out=None)

    Return the transposed matrix.

    Collective.

    Parameters:

      out (Mat | None) – Optional return matrix. If `None`, inplace transposition is performed. Otherwise, the matrix is reused.

    Return type:

      Mat

    See also

    `MatTranspose`

    Source code at petsc4py/PETSc/Mat.pyx:2310

  transposeMatMult(mat, result=None, fill=None)

    Perform matrix-matrix multiplication C=AᵀB.

    Neighborwise collective.

    Parameters:

      - mat (Mat) – The right hand matrix B.

      - result (Mat | None) – The optional resultant matrix C. When `None`, a new matrix is created, and `MAT_INITIAL_MATRIX` is used. When C is not `None`, the matrix is reused with `MAT_REUSE_MATRIX`.

      - fill (float | None) – Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)), use `None` if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

    Returns:

      result – The resultant product matrix C.

    Return type:

      `Mat`

    Notes

    To determine the correct fill value, run with -info and search for the string “Fill ratio” to see the value actually needed.

    See also

    `MatTransposeMatMult`, `MatReuse`

    Source code at petsc4py/PETSc/Mat.pyx:4542

  updateLMVM(x, f)

    Adds (X-Xprev) and (F-Fprev) updates to LMVM matrix.

    Logically collective.

    Parameters:

      - x (Vec) – Solution vector.

      - f (Vec) – Function vector.

    Return type:

      None

    See also

    `MatLMVMUpdate`

    Source code at petsc4py/PETSc/Mat.pyx:5446

  view(viewer=None)

    View the matrix.

    Collective.

    Parameters:

      viewer (Viewer | None) – A `Viewer` instance or `None` for the default viewer.

    Return type:

      None

    Notes

    Viewers with type `Viewer.Type.ASCII` are only recommended for small matrices on small numbers of processes. Larger matrices should use a binary format like `Viewer.Type.BINARY`.

    See also

    `load`, `Viewer`, `MatView`

    Source code at petsc4py/PETSc/Mat.pyx:478

  zeroEntries()

    Zero the entries of the matrix.

    Collective.

    See also

    `MatZeroEntries`

    Source code at petsc4py/PETSc/Mat.pyx:2606

    Return type:

      None

  zeroRows(rows, diag=1.0, x=None, b=None)

    Zero selected rows of the matrix.

    Collective.

    Parameters:

      - rows (IS | Sequence[int]) – Row indices to be zeroed.

      - diag (Scalar) – Scalar value to be inserted into the diagonal.

      - x (Vec | None) – Optional solution vector to be modified for zeroed rows.

      - b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

    Return type:

      None

    See also

    `zeroRowsLocal`, `MatZeroRows`, `MatZeroRowsIS`

    Source code at petsc4py/PETSc/Mat.pyx:3357

  zeroRowsColumns(rows, diag=1.0, x=None, b=None)

    Zero selected rows and columns of the matrix.

    Collective.

    Parameters:

      - rows (IS | Sequence[int]) – Row/column indices to be zeroed.

      - diag (Scalar) – Scalar value to be inserted into the diagonal.

      - x (Vec | None) – Optional solution vector to be modified for zeroed rows.

      - b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

    Return type:

      None

    See also

    `zeroRowsColumnsLocal`, `zeroRows`, `MatZeroRowsColumns`, `MatZeroRowsColumnsIS`

    Source code at petsc4py/PETSc/Mat.pyx:3423

  zeroRowsColumnsLocal(rows, diag=1.0, x=None, b=None)

    Zero selected rows and columns of the matrix in local ordering.

    Collective.

    Parameters:

      - rows (IS | Sequence[int]) – Local row/column indices to be zeroed.

      - diag (Scalar) – Scalar value to be inserted into the diagonal.

      - x (Vec | None) – Optional solution vector to be modified for zeroed rows.

      - b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

    Return type:

      None

    See also

    `zeroRowsLocal`, `zeroRowsColumns`, `MatZeroRowsColumnsLocal`, `MatZeroRowsColumnsLocalIS`

    Source code at petsc4py/PETSc/Mat.pyx:3457

  zeroRowsColumnsStencil(rows, diag=1.0, x=None, b=None)

    Zero selected rows and columns of the matrix.

    Collective.

    Parameters:

      - rows (Sequence[Stencil]) – Iterable of stencil rows and columns.

      - diag (Scalar) – Scalar value to be inserted into the diagonal.

      - x (Vec | None) – Optional solution vector to be modified for zeroed rows.

      - b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

    Return type:

      None

    See also

    `zeroRowsLocal`, `zeroRowsColumns`, `MatZeroRowsColumnsStencil`

    Source code at petsc4py/PETSc/Mat.pyx:3491

  zeroRowsLocal(rows, diag=1.0, x=None, b=None)

    Zero selected rows of the matrix in local ordering.

    Collective.

    Parameters:

      - rows (IS | Sequence[int]) – Local row indices to be zeroed.

      - diag (Scalar) – Scalar value to be inserted into the diagonal.

      - x (Vec | None) – Optional solution vector to be modified for zeroed rows.

      - b (Vec | None) – Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

    Return type:

      None

    See also

    `zeroRows`, `MatZeroRowsLocal`, `MatZeroRowsLocalIS`

    Source code at petsc4py/PETSc/Mat.pyx:3390

  Attributes Documentation

  assembled

    The boolean flag indicating if the matrix is assembled.

    Source code at petsc4py/PETSc/Mat.pyx:6159

  block_size

    Matrix block size.

    Source code at petsc4py/PETSc/Mat.pyx:6137

  block_sizes

    Matrix row and column block sizes.

    Source code at petsc4py/PETSc/Mat.pyx:6142

  hermitian

    The boolean flag indicating if the matrix is Hermitian.

    Source code at petsc4py/PETSc/Mat.pyx:6167

  local_size

    Matrix local size.

    Source code at petsc4py/PETSc/Mat.pyx:6132

  owner_range

    Matrix local row range.

    Source code at petsc4py/PETSc/Mat.pyx:6147

  owner_ranges

    Matrix row ranges.

    Source code at petsc4py/PETSc/Mat.pyx:6152

  size

    Matrix global size.

    Source code at petsc4py/PETSc/Mat.pyx:6127

  sizes

    Matrix local and global sizes.

    Source code at petsc4py/PETSc/Mat.pyx:6119

  structsymm

    The boolean flag indicating if the matrix is structurally symmetric.

    Source code at petsc4py/PETSc/Mat.pyx:6171

  symmetric

    The boolean flag indicating if the matrix is symmetric.

    Source code at petsc4py/PETSc/Mat.pyx:6163

  __init__()
  classmethod __new__(*args, **kwargs)