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

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.

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

H2OpusOrthogonalize()#

Orthogonalize the basis tree of a hierarchical matrix.

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

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.

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

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

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

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

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

MatBindToCPU

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

boundToCPU()#

Query if a matrix is bound to the CPU.

See also

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

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

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

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

MatCopy, 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, 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

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

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.

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

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

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

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

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.

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

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

MATLRC, 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

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.

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.

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

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

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]

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

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

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.

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.

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.

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.

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

destroy()#

Destroy the matrix.

Collective.

See also

create, 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

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

MatDuplicate

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

equal(mat)#

Return the result of matrix comparison.

Collective.

See also

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

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

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

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

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

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

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

getBlockSize()#

Return the matrix block size.

Not collective.

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

Return type:

int

getBlockSizes()#

Return the row and column block sizes.

Not collective.

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

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

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

getDM()#

Return the DM defining the data layout of the matrix.

Not collective.

See also

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

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

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

MatDenseGetLDA

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

Return type:

int

getDenseLocalMatrix()#

Return the local part of the dense matrix.

Not collective.

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

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

getDiagonalBlock()#

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

Not collective.

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

Return type:

Mat

getISLocalMat()#

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

See also

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

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

MatInfo, MatGetInfo

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

getLGMap()#

Return the local-to-global mappings.

Not collective.

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

MatLRCGetMats

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

getLocalSize()#

Return the local number of rows and columns.

Not collective.

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

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

getMumpsCntl(icntl)#

Return the MUMPS parameter, CNTL[icntl].

Logically collective.

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

Parameters:

icntl (int) –

Return type:

float

getMumpsIcntl(icntl)#

Return the MUMPS parameter, ICNTL[icntl].

Logically collective.

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

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

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

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

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

getNearNullSpace()#

Return the near-nullspace.

Not collective.

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

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.

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

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

MatNestGetSubMat

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

getNullSpace()#

Return the nullspace.

Not collective.

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

Return type:

NullSpace

getOption(option)#

Return the option value.

Not collective.

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.

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

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.

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

Return type:

tuple[IS, IS]

getOwnershipRange()#

Return the locally owned range of rows.

Not collective.

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

Return type:

tuple[int, int]

getOwnershipRangeColumn()#

Return the locally owned range of columns.

Not collective.

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.

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

Return type:

ArrayInt

getOwnershipRangesColumn()#

Return the range of columns owned by each process.

Not collective.

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.

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

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

getRow(row)#

Return the column indices and values for the requested row.

Not collective.

See also

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

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

MatGetRowSum

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

getSize()#

Return the global number of rows and columns.

Not collective.

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.

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

Return type:

NullSpace

getType()#

Return the type of the matrix.

Not collective.

See also

setType, Type, 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

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

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

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.

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

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

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

increaseOverlap(iset, overlap=1)#

Increase the overlap of a index set.

Collective.

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.

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

Return type:

ArrayScalar

isAssembled()#

The boolean flag indicating if the matrix is assembled.

Not collective.

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

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.

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

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.

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

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

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

load(viewer)#

Load a matrix.

Collective.

See also

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

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

MatMatMult, 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

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.

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

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

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

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

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

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

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

MatNorm, 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

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

See also

MatPtAP, 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

MatRARt, 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

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

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

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

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.

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

retrieveValues()#

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

Collective.

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

Return type:

None

scale(alpha)#

Scale the matrix.

Collective.

See also

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

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

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

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

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

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

setFromOptions()#

Configure the matrix from the options database.

Collective.

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

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

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

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

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.

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

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

setNearNullSpace(nsp)#

Set the near-nullspace.

Collective.

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

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

setNullSpace(nsp)#

Set the nullspace.

Collective.

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

Parameters:

nsp (NullSpace) –

Return type:

None

setOption(option, flag)#

Set option.

Collective.

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.

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.

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

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

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.

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

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]])

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

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

Set matrix stencil.

Not collective.

See also

MatSetStencil

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

Parameters:
Return type:

None

setTransposeNullSpace(nsp)#

Set the transpose nullspace.

Collective.

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

Parameters:

nsp (NullSpace) –

Return type:

None

setTransposePrecursor(out)#

Set transpose precursor.

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

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

setUnfactored()#

Set a factored matrix to be treated as unfactored.

Logically collective.

See also

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

shift(alpha)#

Shift the matrix.

Collective.

See also

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

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

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

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

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

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

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

storeValues()#

Stash a copy of the matrix values.

Collective.

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

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.

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

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

zeroEntries()#

Zero the entries of the matrix.

Collective.

See also

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

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

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

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

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

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