petsc4py.PETSc.Mat

class petsc4py.PETSc.Mat

Bases: Object

Matrix object.

Mat is described in the PETSc manual.

See also

petsc.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[, 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.

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.

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.

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.

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.

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.

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.

Parameters:

tol (float) – The absolute truncation threshold.

See also

petsc.MatH2OpusCompress

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

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

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

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.

See also

petsc.MatH2OpusLowRankUpdate

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

H2OpusOrthogonalize()

Orthogonalize the basis tree of a hierarchical matrix.

See also

petsc.MatH2OpusOrthogonalize

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

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

petsc.MatSOR

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

Parameters:
Return type:

None

appendOptionsPrefix(prefix)

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

Logically collective.

See also

Working with PETSc options (TODO), setOptionsPrefix, petsc.MatAppendOptionsPrefix

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

Parameters:

prefix (str) –

Return type:

None

assemble(assembly=None)

Assemble the matrix.

Collective.

Parameters:

assembly (MatAssemblySpec) – The assembly type.

Return type:

None

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

assemblyBegin(assembly=None)

Begin an assembling stage of the matrix.

Collective.

Parameters:

assembly (MatAssemblySpec) – The assembly type.

Return type:

None

See also

assemblyEnd, assemble, petsc.MatAssemblyBegin

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

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, petsc.MatAssemblyEnd

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

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

petsc.MatAXPY

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

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

petsc.MatAYPX

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

bindToCPU(flg)

Mark a matrix to temporarily stay on the CPU.

Once marked, perform computations on the CPU.

Parameters:

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

Return type:

None

See also

petsc.MatBindToCPU

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

boundToCPU()

Query if a matrix is bound to the CPU.

See also

petsc.MatBoundToCPU

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

Return type:

bool

chop(tol)

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

Collective.

See also

petsc.MatFilter

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

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, petsc.MatConjugate

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

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

petsc.MatConvert

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

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

petsc.MatCopy, petsc.MatDuplicate

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

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, petsc.MatCreate

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

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:
Return type:

Self

See also

setSizes, createBAIJ, petsc.MATAIJ, petsc.MATSEQAIJ, petsc.MATMPIAIJ, petsc.MatCreateAIJ, petsc.MatSeqAIJSetPreallocation, petsc.MatSeqAIJSetPreallocationCSR

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

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:
Return type:

Self

See also

createAIJ, createBAIJ, petsc.MatCreateSeqAIJCRL, petsc.MatCreateMPIAIJCRL

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

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

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

Collective.

Parameters:
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, petsc.MatCreateSeqAIJWithArrays, petsc.MatCreateMPIAIJWithArrays, petsc.MatCreateMPIAIJWithSplitArrays

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

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:
Return type:

Self

See also

setSizes, createAIJ, petsc.MATBAIJ, petsc.MATSEQBAIJ, petsc.MATMPIBAIJ, petsc.MatCreateBAIJ

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

createConstantDiagonal(size, diag, comm=None)

Create a diagonal matrix of type Type.CONSTANTDIAGONAL.

Collective.

Parameters:
Return type:

Self

See also

createDiagonal

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

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

Create a Type.DENSE matrix.

Collective.

Parameters:
Return type:

Self

See also

createDenseCUDA, petsc.MATDENSE, petsc.MatCreateDense

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

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

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

Collective.

Parameters:
Return type:

Self

See also

createDense, petsc.MatCreateDenseCUDA

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

createDiagonal(diag)

Create a diagonal matrix of type Type.DIAGONAL.

Collective.

Parameters:

diag (Vec) – The vector holding diagonal values.

Return type:

Self

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

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.

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 petsc.MatCreateH2OpusFromMat for the appropriate database options.

See also

Working with PETSc options (TODO), petsc.MatCreateH2OpusFromMat

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

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, petsc.MATHERMITIANTRANSPOSEVIRTUAL, petsc.MatCreateHermitianTranspose

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

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

Create a Type.IS matrix representing globally unassembled operators.

Collective.

Parameters:
  • size (MatSizeSpec) – Matrix size.

  • 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

petsc.MATIS

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

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

petsc.MATLRC, petsc.MatCreateLRC

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

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

petsc.MatCreateNest, petsc.MATNEST

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

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

petsc.MATNORMAL, petsc.MatCreateNormal

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

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, petsc.MATNORMAL, petsc.MATNORMALHERMITIAN, petsc.MatCreateNormalHermitian

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

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

Create a Type.PYTHON matrix.

Collective.

Parameters:
Return type:

Self

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

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 (int) – 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, petsc.MatCreateSBAIJ

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

createScatter(scatter, comm=None)

Create a Type.SCATTER matrix from a vector scatter.

Collective.

Parameters:
Return type:

Self

See also

petsc.MATSCATTER, petsc.MatCreateScatter

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

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

petsc.MatCreateSubMatrices

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

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

petsc.MatCreateSubMatrix

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

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

petsc.MatCreateSubMatrixVirtual

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

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, petsc.MatCreateTranspose

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

createVecLeft()

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

Collective.

See also

createVecs, createVecRight, petsc.MatCreateVecs

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

Return type:

Vec

createVecRight()

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

Collective.

See also

createVecs, createVecLeft, petsc.MatCreateVecs

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

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, petsc.MatCreateVecs

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

destroy()

Destroy the matrix.

Collective.

See also

create, petsc.MatDestroy

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

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

petsc.MatDiagonalScale

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

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

petsc.MatDuplicate

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

equal(mat)

Return the result of matrix comparison.

Collective.

See also

petsc.MatEqual

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

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, petsc.MatCholeskyFactor

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

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, petsc.MatICCFactor

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

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

petsc.MatILUFactor

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

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

petsc.MatLUFactor

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

factorNumericCholesky(mat, options=None)

Not implemented.

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

Parameters:

mat (Mat) –

Return type:

None

factorNumericLU(mat, options=None)

Not implemented.

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

Parameters:

mat (Mat) –

Return type:

None

factorSymbolicCholesky(isperm, options=None)

Not implemented.

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

Parameters:

isperm (IS) –

Return type:

None

factorSymbolicICC(isperm, options=None)

Not implemented.

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

Parameters:

isperm (IS) –

Return type:

None

factorSymbolicILU(isrow, iscol, options=None)

Not implemented.

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

Parameters:
  • isrow (IS) –

  • iscol (IS) –

Return type:

None

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

Not implemented.

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

Parameters:
  • mat (Mat) –

  • isrow (IS) –

  • iscol (IS) –

Return type:

None

findZeroRows()

Return the index set of empty rows.

Collective.

See also

petsc.MatFindZeroRows

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

Return type:

IS

fixISLocalEmpty(fix)

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

petsc.MatISFixLocalEmpty

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

getBlockSize()

Return the matrix block size.

Not collective.

See also

getBlockSize, petsc.MatGetBlockSize

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

Return type:

int

getBlockSizes()

Return the row and column block sizes.

Not collective.

See also

getBlockSize, petsc.MatGetBlockSizes

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

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

petsc.MatGetRowIJ

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

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

petsc.MatGetColumnVector

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

getDM()

Return the DM defining the data layout of the matrix.

Not collective.

See also

petsc.MatGetDM

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

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

petsc.MatDenseGetArrayRead, petsc.MatDenseGetArray

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

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, petsc.MatDenseGetColumnVec, petsc.MatDenseGetColumnVecRead, petsc.MatDenseGetColumnVecWrite

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

getDenseLDA()

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

Not collective.

See also

petsc.MatDenseGetLDA

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

Return type:

int

getDenseLocalMatrix()

Return the local part of the dense matrix.

Not collective.

See also

petsc.MatDenseGetLocalMatrix

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

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, petsc.MatGetDiagonal

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

getDiagonalBlock()

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

Not collective.

See also

petsc.MatGetDiagonalBlock

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

Return type:

Mat

getISLocalMat()

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

See also

petsc.MatISGetLocalMat

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

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

petsc.MatGetInertia

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

getInfo(info=None)

Return summary information.

Collective.

Parameters:

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

Return type:

dict[str, float]

See also

petsc.MatInfo, petsc.MatGetInfo

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

getLGMap()

Return the local-to-global mappings.

Not collective.

See also

setLGMap, petsc.MatGetLocalToGlobalMapping

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

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

petsc.MatLRCGetMats

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

getLocalSize()

Return the local number of rows and columns.

Not collective.

See also

getSize, petsc.MatGetLocalSize

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

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, petsc.MatGetLocalSubMatrix

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

getMumpsCntl(icntl)

Return the MUMPS parameter, CNTL[icntl].

Logically collective.

See also

Working with PETSc options (TODO), petsc.MatMumpsGetCntl

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

Parameters:

icntl (int) –

Return type:

float

getMumpsIcntl(icntl)

Return the MUMPS parameter, ICNTL[icntl].

Logically collective.

See also

Working with PETSc options (TODO), petsc.MatMumpsGetIcntl

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

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

petsc.MatMumpsGetInfo

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

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

petsc.MatMumpsGetInfog

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

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

petsc.MatMumpsGetRinfo

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

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

petsc.MatMumpsGetRinfog

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

getNearNullSpace()

Return the near-nullspace.

Not collective.

See also

getNullSpace, setNearNullSpace, petsc.MatSetNearNullSpace

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

Return type:

NullSpace

getNestISs()

Return the index sets representing the row and column spaces.

Not collective.

See also

petsc.MatNestGetISs

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

Return type:

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

getNestLocalISs()

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

Not collective.

See also

petsc.MatNestGetLocalISs

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

Return type:

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

getNestSize()

Return the number of rows and columns of the matrix.

Not collective.

See also

petsc.MatNestGetSize

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

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

petsc.MatNestGetSubMat

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

getNullSpace()

Return the nullspace.

Not collective.

See also

setNullSpace, petsc.MatGetNullSpace

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

Return type:

NullSpace

getOption(option)

Return the option value.

Not collective.

See also

setOption, petsc.MatGetOption

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

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 (TODO), setOptionsPrefix, petsc.MatGetOptionsPrefix

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

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

petsc.MatGetOrdering

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

getOwnershipIS()

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

Not collective.

See also

getOwnershipRanges, getOwnershipRangesColumn, petsc.MatGetOwnershipIS

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

Return type:

tuple[IS, IS]

getOwnershipRange()

Return the locally owned range of rows.

Not collective.

See also

getOwnershipRanges, getOwnershipRangeColumn, petsc.MatGetOwnershipRange

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

Return type:

tuple[int, int]

getOwnershipRangeColumn()

Return the locally owned range of columns.

Not collective.

See also

getOwnershipRangesColumn, getOwnershipRange, petsc.MatGetOwnershipRangeColumn

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

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, petsc.MatGetOwnershipRanges

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

Return type:

ArrayInt

getOwnershipRangesColumn()

Return the range of columns owned by each process.

Not collective.

See also

getOwnershipRangeColumn, petsc.MatGetOwnershipRangesColumn

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

Return type:

ArrayInt

getPythonContext()

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

Not collective.

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

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, petsc.MatPythonGetType

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

Return type:

str

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

Return redundant matrices on subcommunicators.

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

petsc.MatCreateRedundantMatrix

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

getRow(row)

Return the column indices and values for the requested row.

Not collective.

See also

petsc.MatGetRow

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

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

petsc.MatGetRowIJ

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

getRowSum(result=None)

Return the row-sum vector.

Collective.

Parameters:

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

Return type:

Vec

See also

petsc.MatGetRowSum

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

getSize()

Return the global number of rows and columns.

Not collective.

See also

getLocalSize, getSizes, petsc.MatGetSize

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

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

Return type:

tuple[LayoutSizeSpec, LayoutSizeSpec]

getTransposeNullSpace()

Return the transpose nullspace.

Not collective.

See also

getNullSpace, setTransposeNullSpace, petsc.MatGetTransposeNullSpace

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

Return type:

NullSpace

getType()

Return the type of the matrix.

Not collective.

See also

setType, Type, petsc.MatGetType

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

Return type:

str

getValue(row, col)

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

Not collective.

See also

petsc.MatGetValues

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

Return type:

Scalar

getValues(rows, cols, values=None)

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

Not collective.

Parameters:
Return type:

ArrayScalar

See also

petsc.MatGetValues

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

getValuesCSR()

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

Not collective.

See also

petsc.MatGetRow

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

Return type:

tuple[ArrayInt, ArrayInt, ArrayScalar]

getVecType()

Return the vector type used by the matrix.

Not collective.

See also

setVecType, petsc.MatGetVecType

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

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

petsc.MatHermitianTranspose

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

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, petsc.MatImaginaryPart

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

increaseOverlap(iset, overlap=1)

Increase the overlap of a index set.

Collective.

See also

petsc.MatIncreaseOverlap

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

Parameters:
  • iset (IS) –

  • overlap (int) –

Return type:

None

invertBlockDiagonal()

Return the inverse of the block-diagonal entries.

Collective.

See also

petsc.MatInvertBlockDiagonal

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

Return type:

ArrayScalar

isAssembled()

The boolean flag indicating if the matrix is assembled.

Not collective.

See also

assemble, petsc.MatAssembled

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

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

petsc.MatIsHermitian

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

isHermitianKnown()

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

Not collective.

See also

petsc.MatIsHermitianKnown

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

Return type:

tuple[bool, bool]

isStructurallySymmetric()

Return the boolean indicating if the matrix is structurally symmetric.

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

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

petsc.MatIsSymmetric

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

isSymmetricKnown()

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

Not collective.

See also

petsc.MatIsSymmetricKnown

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

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

petsc.MatIsTranspose

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

kron(mat, result=None)

Compute C, the Kronecker product of A and B.

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

petsc.MatSeqAIJKron, petsc.MatReuse

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

load(viewer)

Load a matrix.

Collective.

See also

petsc.MatLoad

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

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

petsc.MatMatMatMult, petsc.MatReuse

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

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

petsc.MatMatMult, petsc.MatReuse

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

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, petsc.MatMatSolve

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

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

petsc.MatMatTransposeMult, petsc.MatReuse

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

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

petsc.MatMult

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

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

petsc.MatMultAdd

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

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

petsc.MatMultHermitianTranspose

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

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

petsc.MatMultHermitianTransposeAdd

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

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

petsc.MatMultTranspose

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

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

petsc.MatMultTransposeAdd

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

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

petsc.MatNorm, petsc.NormType

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

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

petsc.MatPermute

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

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 petsc.MatProductCreate and set the desired options before the computation is done.

See also

petsc.MatPtAP, petsc.MatReuse

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

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

petsc.MatRARt, petsc.MatReuse

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

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, petsc.MatRealPart

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

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, petsc.MatReorderForNonzeroDiagonal

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

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, petsc.MatDenseRestoreColumnVec, petsc.MatDenseRestoreColumnVecRead, petsc.MatDenseRestoreColumnVecWrite

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

restoreISLocalMat(local)

Restore the local matrix obtained with getISLocalMat.

Parameters:

local (Mat) – The local matrix.

Return type:

None

See also

petsc.MatISRestoreLocalMat

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

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.

See also

getLocalSubMatrix, petsc.MatRestoreLocalSubMatrix

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

retrieveValues()

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

Collective.

See also

storeValues, petsc.MatRetrieveValues

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

Return type:

None

scale(alpha)

Scale the matrix.

Collective.

See also

petsc.MatScale

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

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, petsc.MatSetBlockSize

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

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, petsc.MatSetBlockSizes

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

setDM(dm)

Set the DM defining the data layout of the matrix.

Not collective.

Parameters:

dm (DM) – The DM.

Return type:

None

See also

petsc.MatSetDM

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

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

petsc.MatDenseSetLDA

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

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, petsc.MatDiagonalSet

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

setFromOptions()

Configure the matrix from the options database.

Collective.

See also

Working with PETSc options (TODO), petsc.MatSetFromOptions

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

Return type:

None

setISLocalMat(local)

Set the local matrix stored inside a Type.IS.

Parameters:

local (Mat) – The local matrix.

Return type:

None

See also

petsc.MatISSetLocalMat

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

setISPreallocation(nnz, onnz)

Preallocate memory for a Type.IS parallel matrix.

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

petsc.MatISSetPreallocation

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

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, petsc.MatSetLocalToGlobalMapping

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

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.

See also

petsc.MatLRCSetMats

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

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.

See also

Working with PETSc options (TODO), petsc.MatMumpsSetCntl

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

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 (TODO), petsc.MatMumpsSetIcntl

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

setNearNullSpace(nsp)

Set the near-nullspace.

Collective.

See also

setNullSpace, getNearNullSpace, petsc.MatSetNearNullSpace

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

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, petsc.MatNestSetVecType

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

setNullSpace(nsp)

Set the nullspace.

Collective.

See also

getNullSpace, petsc.MatSetNullSpace

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

Parameters:

nsp (NullSpace) –

Return type:

None

setOption(option, flag)

Set option.

Collective.

See also

getOption, petsc.MatSetOption

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

Parameters:
Return type:

None

setOptionsPrefix(prefix)

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

Logically collective.

See also

Working with PETSc options (TODO), getOptionsPrefix, petsc.MatSetOptionsPrefix

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

Parameters:

prefix (str) –

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, petsc.MatSeqAIJSetPreallocationCSR, petsc.MatMPIAIJSetPreallocationCSR, petsc.MatSeqBAIJSetPreallocationCSR, petsc.MatMPIBAIJSetPreallocationCSR, petsc.MatSeqSBAIJSetPreallocationCSR, petsc.MatMPISBAIJSetPreallocationCSR

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

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

petsc.MatSeqDenseSetPreallocation, petsc.MatMPIDenseSetPreallocation

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

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, petsc.MatSeqAIJSetPreallocation, petsc.MatMPIAIJSetPreallocation

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

setPythonContext(context)

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

Not collective.

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

Parameters:

context (Any) –

Return type:

None

setPythonType(py_type)

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

Collective.

See also

PETSc Python matrix type, setPythonContext, getPythonType, petsc.MatPythonSetType

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

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

petsc.MatSetRandom

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

setSizes(size, bsize=None)

Set the local, global and block sizes.

Collective.

Parameters:
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, petsc.MatSetSizes, petsc.MatSetBlockSize, petsc.MatSetBlockSizes

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

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

Set matrix stencil.

Not collective.

See also

petsc.MatSetStencil

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

Parameters:
Return type:

None

setTransposeNullSpace(nsp)

Set the transpose nullspace.

Collective.

See also

setNullSpace, getTransposeNullSpace, petsc.MatSetTransposeNullSpace

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

Parameters:

nsp (NullSpace) –

Return type:

None

setTransposePrecursor(out)

Set transpose precursor.

See also

petsc.MatTransposeSetPrecursor

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

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, petsc.MatSetType

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

setUnfactored()

Set a factored matrix to be treated as unfactored.

Logically collective.

See also

petsc.MatSetUnfactored

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

Return type:

None

setUp()

Set up the internal data structures for using the matrix.

Collective.

See also

petsc.MatSetUp

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

Return type:

None

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

petsc.MatSetValues

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

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

Not implemented.

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

Return type:

None

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

Set a block of values to row and col stencil.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesBlockedStencil

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

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

petsc.MatSetValuesLocal

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

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

Not implemented.

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

Return type:

None

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

Set a value to row and col stencil.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesStencil

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

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

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

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValues

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

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

petsc.MatSetValuesBlocked

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

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

Set values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesBlocked

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

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

Set a subset of values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesBlocked

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

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

petsc.MatSetValuesBlockedLocal

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

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

Set values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesBlockedLocal

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

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

Set a subset of values stored in block CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesBlockedLocal

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

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

Undocumented.

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

Return type:

None

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

Undocumented.

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

Return type:

None

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

Set values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValues

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

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

Set a subset of values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValues

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

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

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

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesLocal

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

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

Set values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesLocal

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

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

Set a subset of values stored in CSR format.

Not collective.

Parameters:
Return type:

None

See also

petsc.MatSetValuesLocal

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

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

Undocumented.

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

Return type:

None

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

Undocumented.

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

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, petsc.MatSetVecType

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

shift(alpha)

Shift the matrix.

Collective.

See also

petsc.MatShift

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

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, petsc.MatSolve

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

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, petsc.MatSolve, petsc.MatSolveAdd

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

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

petsc.MatBackwardSolve

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

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

petsc.MatForwardSolve

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

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, petsc.MatSolve, petsc.MatSolveTranspose

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

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, petsc.MatSolve, petsc.MatSolveTransposeAdd

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

storeValues()

Stash a copy of the matrix values.

Collective.

See also

retrieveValues, petsc.MatStoreValues

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

Return type:

None

toDLPack(mode='rw')

Return a DLPack PyCapsule wrapping the vector data.

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

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

petsc.MatTranspose

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

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

petsc.MatTransposeMatMult, petsc.MatReuse

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

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, petsc.MatView

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

zeroEntries()

Zero the entries of the matrix.

Collective.

See also

petsc.MatZeroEntries

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

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, petsc.MatZeroRows, petsc.MatZeroRowsIS

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

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, petsc.MatZeroRowsColumns, petsc.MatZeroRowsColumnsIS

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

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, petsc.MatZeroRowsColumnsLocal, petsc.MatZeroRowsColumnsLocalIS

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

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, petsc.MatZeroRowsColumnsStencil

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

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, petsc.MatZeroRowsLocal, petsc.MatZeroRowsLocalIS

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

Attributes Documentation

assembled

The boolean flag indicating if the matrix is assembled.

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

block_size

Matrix block size.

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

block_sizes

Matrix row and column block sizes.

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

hermitian

The boolean flag indicating if the matrix is Hermitian.

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

local_size

Matrix local size.

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

owner_range

Matrix local row range.

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

owner_ranges

Matrix row ranges.

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

size

Matrix global size.

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

sizes

Matrix local and global sizes.

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

structsymm

The boolean flag indicating if the matrix is structurally symmetric.

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

symmetric

The boolean flag indicating if the matrix is symmetric.

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