# 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.
  `SOR`(b, x[, omega, sortype, shift, its, lits]) | Compute relaxation (SOR, Gauss-Seidel) sweeps.
  `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*)ᵀ.
  `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.
  `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.
  `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.
  `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.
  `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.
  `restoreDenseColumnVec`(i[, mode]) | Restore the iᵗʰ column vector of the 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.
  `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.
  `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.
  `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.
  `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:4992

  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:5011

  H2OpusOrthogonalize()

    Orthogonalize the basis tree of a hierarchical matrix.

    Collective.

    See also

    `MatH2OpusOrthogonalize`

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

    Return type:

      Self

  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:3825

    Parameters:

      - b (Vec)

      - x (Vec)

      - omega (float)

      - sortype (SORType | None)

      - shift (float)

      - its (int)

      - lits (int)

    Return type:

      None

  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:1751

    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:3338

  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:3302

  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:3320

  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) – The structure of the operation.

    Return type:

      None

    See also

    `MatAXPY`

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

  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) – The structure of the operation.

    Return type:

      None

    See also

    `MatAYPX`

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

  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:4520

  boundToCPU()

    Query if a matrix is bound to the CPU.

    Not collective.

    See also

    `MatBoundToCPU`

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

    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:4121

    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:2215

  convert(mat_type=None, out=None)

    Convert the matrix type.

    Collective.

    Parameters:

      - mat_type (Type | str) – 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:2071

  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:2026

  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:488

  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 (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:693

  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 (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:826

  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:956

  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 (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:738

  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:1561

  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:1047

  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:1083

  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:1594

  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:1427

  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:1263

  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:1508

  createLRC(A, U, c, V)

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

    Collective.

    Parameters:

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

      - U (Mat) – Dense rectangular matrices.

      - V (Mat) – Dense rectangular matrices.

      - c (Vec) – Vector containing the diagonal of C, can be `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:1288

  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:1360

  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:1188

  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:1238

  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:1617

  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 (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:782

  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:1164

  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) – preconditioning matrix for use 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:3969

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

    Return several sequential submatrices.

    Collective.

    Parameters:

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

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

      - submats (Mat | Sequence[Mat]) – 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:3912

  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:3882

  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:1335

  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:1213

  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:3438

    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:3424

    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 return a left or right vector.

    Return type:

      Vec | tuple[Vec, Vec]

    Notes

    `right` vectors are vectors in the column space of the matrix. `left` vectors are vectors in the row space of the matrix.

    See also

    `createVecLeft`, `createVecRight`, `MatCreateVecs`

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

  destroy()

    Destroy the matrix.

    Collective.

    See also

    `create`, `MatDestroy`

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

    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:3577

  duplicate(copy=False)

    Return a clone of the matrix.

    Collective.

    Parameters:

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

    Return type:

      Mat

    See also

    `MatDuplicate`

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

  equal(mat)

    Return the result of matrix comparison.

    Collective.

    See also

    `MatEqual`

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

    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:4684

  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:4717

  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:4650

  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:4612

  factorNumericCholesky(mat, options=None)

    Not implemented.

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

    Parameters:

      mat (Mat)

    Return type:

      None

  factorNumericLU(mat, options=None)

    Not implemented.

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

    Parameters:

      mat (Mat)

    Return type:

      None

  factorSymbolicCholesky(isperm, options=None)

    Not implemented.

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

    Parameters:

      isperm (IS)

    Return type:

      None

  factorSymbolicICC(isperm, options=None)

    Not implemented.

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

    Parameters:

      isperm (IS)

    Return type:

      None

  factorSymbolicILU(isrow, iscol, options=None)

    Not implemented.

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

    Parameters:

      - isrow (IS)

      - iscol (IS)

    Return type:

      None

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

    Not implemented.

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

    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:3371

    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:4817

  getBlockSize()

    Return the matrix block size.

    Not collective.

    See also

    `getBlockSize`, `MatGetBlockSize`

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

    Return type:

      int

  getBlockSizes()

    Return the row and column block sizes.

    Not collective.

    See also

    `getBlockSize`, `MatGetBlockSizes`

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

    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:2518

  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:3458

  getDM()

    Return the DM defining the data layout of the matrix.

    Not collective.

    See also

    `MatGetDM`

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

    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:5375

  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 returned array

    Return type:

      Vec

    See also

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

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

  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:5361

    Return type:

      int

  getDenseLocalMatrix()

    Return the local part of the dense matrix.

    Not collective.

    See also

    `MatDenseGetLocalMatrix`

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

    Return type:

      Mat

  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:3513

  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:3854

    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:4803

    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:4836

    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:4746

  getInfo(info=None)

    Return summary information.

    Collective.

    Parameters:

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

    Return type:

      dict[str, float]

    See also

    `MatInfo`, `MatGetInfo`

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

  getLGMap()

    Return the local-to-global mappings.

    Not collective.

    See also

    `setLGMap`, `MatGetLocalToGlobalMapping`

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

    Return type:

      tuple[LGMap, LGMap]

  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:4918

  getLocalSize()

    Return the local number of rows and columns.

    Not collective.

    See also

    `getSize`, `MatGetLocalSize`

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

    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:4024

  getMumpsCntl(icntl)

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

    Logically collective.

    See also

    Working with PETSc options, `MatMumpsGetCntl`

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

    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:5060

    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:5111

  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:5131

  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:5151

  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:5171

  getNearNullSpace()

    Return the near-nullspace.

    Not collective.

    See also

    `getNullSpace`, `setNearNullSpace`, `MatSetNearNullSpace`

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

    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:5502

    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:5523

    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:5488

    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:5544

  getNullSpace()

    Return the nullspace.

    Not collective.

    See also

    `setNullSpace`, `MatGetNullSpace`

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

    Return type:

      NullSpace

  getOption(option)

    Return the option value.

    Not collective.

    See also

    `setOption`, `MatGetOption`

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

    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:1737

    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:4556

  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:1969

    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:1902

    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:1936

    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:1916

    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:1951

    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:1671

    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:1706

    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:3483

  getRow(row)

    Return the column indices and values for the requested row.

    Not collective.

    See also

    `MatGetRow`

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

    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:2487

  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:3535

  getSchurComplementSubMatrices()

    Return Schur complement sub-matrices.

    Collective.

    See also

    `MatSchurComplementGetSubMatrices`

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

    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:1830

    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:1858

    Return type:

      tuple[LayoutSizeSpec, LayoutSizeSpec]

  getTransposeNullSpace()

    Return the transpose nullspace.

    Not collective.

    See also

    `getNullSpace`, `setTransposeNullSpace`, `MatGetTransposeNullSpace`

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

    Return type:

      NullSpace

  getType()

    Return the type of the matrix.

    Not collective.

    See also

    `setType`, `Type`, `MatGetType`

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

    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:2392

    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) – Optional array where to store the values.

    Return type:

      ArrayScalar

    See also

    `MatGetValues`

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

  getValuesCSR()

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

    Not collective.

    See also

    `MatGetRow`

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

    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:658

    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:2142

  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:2192

  increaseOverlap(iset, overlap=1)

    Increase the overlap of a index set.

    Collective.

    See also

    `MatIncreaseOverlap`

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

    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:3599

    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:3357

    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:2331

  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:2351

    Return type:

      tuple[bool, bool]

  isStructurallySymmetric()

    Return the boolean indicating if the matrix is structurally symmetric.

    Not collective.

    See also

    `MatIsStructurallySymmetric`

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

    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:2296

  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:2316

    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:2273

  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:4485

  load(viewer)

    Load a matrix.

    Collective.

    See also

    `MatLoad`

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

    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:4440

  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:4201

  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:5321

  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:4248

  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:3703

  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:3722

  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:3783

  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:3802

  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:3743

  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:3762

  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:4073

    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:2238

  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:933

  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:4342

  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:4393

  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:2169

  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:4584

  restoreDenseColumnVec(i, mode='rw')

    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 restored array

    Return type:

      None

    See also

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

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

  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:4851

  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:4050

  retrieveValues()

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

    Collective.

    See also

    `storeValues`, `MatRetrieveValues`

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

    Return type:

      None

  scale(alpha)

    Scale the matrix.

    Collective.

    See also

    `MatScale`

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

    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:586

  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:604

  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:5587

  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:5343

  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:3557

  setFromOptions()

    Configure the matrix from the options database.

    Collective.

    See also

    Working with PETSc options, `MatSetFromOptions`

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

    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:4785

  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:4868

  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:4885

  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:2764

  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:4950

  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:5075

  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:5039

  setNearNullSpace(nsp)

    Set the near-nullspace.

    Collective.

    See also

    `setNullSpace`, `getNearNullSpace`, `MatSetNearNullSpace`

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

    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:672

  setNullSpace(nsp)

    Set the nullspace.

    Collective.

    See also

    `getNullSpace`, `MatSetNullSpace`

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

    Parameters:

      nsp (NullSpace)

    Return type:

      None

  setOption(option, flag)

    Set option.

    Collective.

    See also

    `getOption`, `MatSetOption`

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

    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:1723

    Parameters:

      prefix (str | None)

    Return type:

      None

  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 (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:899

  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:1140

  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:873

  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:1654

    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:1686

    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:4134

  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:533

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

    Set matrix stencil.

    Not collective.

    See also

    `MatSetStencil`

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

    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:3647

    Parameters:

      nsp (NullSpace)

    Return type:

      None

  setTransposePrecursor(out)

    Set transpose precursor.

    Logically collective.

    See also

    `MatTransposeSetPrecursor`

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

    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:514

  setUnfactored()

    Set a factored matrix to be treated as unfactored.

    Logically collective.

    See also

    `MatSetUnfactored`

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

    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:1777

    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:2548

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

    Not implemented.

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

    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:3076

  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:2801

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

    Not implemented.

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

    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:3042

  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:2580

  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:2671

  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:2736

  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]) – Optional iterable indicating which block row to insert.

    Return type:

      None

    See also

    `MatSetValuesBlocked`

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

  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:2925

  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:2990

  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]) – Optional iterable indicating which block row to insert.

    Return type:

      None

    See also

    `MatSetValuesBlockedLocal`

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

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

    Undocumented.

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

    Return type:

      None

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

    Undocumented.

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

    Return type:

      None

  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:2643

  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]) – Optional iterable indicating which row to insert.

    Return type:

      None

    See also

    `MatSetValues`

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

  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:2834

  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:2897

  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]) – Optional iterable indicating which row to insert.

    Return type:

      None

    See also

    `MatSetValuesLocal`

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

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

    Undocumented.

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

    Return type:

      None

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

    Undocumented.

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

    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:625

    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:639

  shift(alpha)

    Shift the matrix.

    Collective.

    See also

    `MatShift`

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

    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:5231

  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:5275

  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:5212

  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:5193

  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:5254

  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:5298

  storeValues()

    Stash a copy of the matrix values.

    Collective.

    See also

    `retrieveValues`, `MatStoreValues`

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

    Return type:

      None

  toDLPack(mode='rw')

    Return a DLPack `PyCapsule` wrapping the vector data.

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

    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:2103

  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:4295

  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:450

  zeroEntries()

    Zero the entries of the matrix.

    Collective.

    See also

    `MatZeroEntries`

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

    Return type:

      None

  zeroRows(rows, diag=1, 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:3110

  zeroRowsColumns(rows, diag=1, 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:3176

  zeroRowsColumnsLocal(rows, diag=1, 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:3210

  zeroRowsColumnsStencil(rows, diag=1, 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:3244

  zeroRowsLocal(rows, diag=1, 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:3143

  Attributes Documentation

  assembled

    The boolean flag indicating if the matrix is assembled.

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

  block_size

    Matrix block size.

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

  block_sizes

    Matrix row and column block sizes.

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

  hermitian

    The boolean flag indicating if the matrix is Hermitian.

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

  local_size

    Matrix local size.

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

  owner_range

    Matrix local row range.

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

  owner_ranges

    Matrix row ranges.

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

  size

    Matrix global size.

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

  sizes

    Matrix local and global sizes.

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

  structsymm

    The boolean flag indicating if the matrix is structurally symmetric.

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

  symmetric

    The boolean flag indicating if the matrix is symmetric.

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