Matrices API Reference

Mat{T}

A distributed PETSc matrix with element type T, managed by SafePETSc's reference counting system.

Mat{T} is actually a type alias for DRef{_Mat{T}}, meaning matrices are automatically tracked across MPI ranks and destroyed collectively when all ranks release their references.

Construction

Use Mat_uniform or Mat_sum to create distributed matrices:

# Create from uniform data (same on all ranks)
A = Mat_uniform([1.0 2.0; 3.0 4.0])

# Create from sparse contributions (summed across ranks)
using SparseArrays
A = Mat_sum(sparse([1, 2], [1, 2], [1.0, 4.0], 2, 2))

Operations

Matrices support standard linear algebra operations:

# Matrix-vector multiplication
y = A * x

# Matrix-matrix multiplication
C = A * B

# Matrix transpose
B = A'
B = Mat(A')  # Materialize transpose

# Linear solve
x = A \ b

# Concatenation
C = vcat(A, B)  # or cat(A, B; dims=1)
D = hcat(A, B)  # or cat(A, B; dims=2)
E = blockdiag(A, B)

# Diagonal matrix from vectors
using SparseArrays
A = spdiagm(0 => diag_vec, 1 => upper_diag)

See also: Mat_uniform, Mat_sum, Vec, Solver

Mat_uniform(A::Matrix{T}; row_partition=default_row_partition(size(A, 1), MPI.Comm_size(MPI.COMM_WORLD)), col_partition=default_row_partition(size(A, 2), MPI.Comm_size(MPI.COMM_WORLD)), prefix="") -> DRef{Mat{T}}

Create a distributed PETSc matrix from a Julia matrix, asserting uniform distribution across ranks (on MPI.COMM_WORLD).

• A::Matrix{T} must be identical on all ranks (mpi_uniform).
• row_partition is a Vector{Int} of length nranks+1 where partition[i] is the start row (1-indexed) for rank i-1.
• col_partition is a Vector{Int} of length nranks+1 where partition[i] is the start column (1-indexed) for rank i-1.
• prefix is an optional string prefix for MatSetOptionsPrefix() to set matrix-specific command-line options.
• Returns a DRef that will destroy the PETSc Mat collectively when all ranks release their reference.

Mat_sum(A::SparseMatrixCSC{T}; row_partition=default_row_partition(size(A, 1), MPI.Comm_size(MPI.COMM_WORLD)), col_partition=default_row_partition(size(A, 2), MPI.Comm_size(MPI.COMM_WORLD)), prefix="", own_rank_only=false) -> DRef{Mat{T}}

Create a distributed PETSc matrix by summing sparse matrices across ranks (on MPI.COMM_WORLD).

• A::SparseMatrixCSC{T} can differ across ranks; nonzero entries are summed across all ranks.
• row_partition is a Vector{Int} of length nranks+1 where partition[i] is the start row (1-indexed) for rank i-1.
• col_partition is a Vector{Int} of length nranks+1 where partition[i] is the start column (1-indexed) for rank i-1.
• prefix is an optional string prefix for MatSetOptionsPrefix() to set matrix-specific command-line options.
• own_rank_only::Bool (default=false): if true, asserts that all nonzero entries fall within this rank's row partition.
• Returns a DRef that will destroy the PETSc Mat collectively when all ranks release their reference.

Uses MatSetValues with ADD_VALUES mode to sum contributions from all ranks.