Vectors API Reference

Vec{T}

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

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

Construction

Use Vec_uniform or Vec_sum to create distributed vectors:

# Create from uniform data (same on all ranks)
v = Vec_uniform([1.0, 2.0, 3.0, 4.0])

# Create from sparse contributions (summed across ranks)
using SparseArrays
v = Vec_sum(sparsevec([1, 3], [1.0, 3.0], 4))

Operations

Vectors support standard arithmetic operations via broadcasting:

y = x .+ 1.0        # Element-wise addition
y .= 2.0 .* x       # In-place scaling
z = x .+ y          # Vector addition

Matrix-vector multiplication:

y = A * x           # Matrix-vector product
LinearAlgebra.mul!(y, A, x)  # In-place version

See also: Vec_uniform, Vec_sum, Mat, zeros_like

Vec_uniform(v::Vector{T}; row_partition=default_row_partition(length(v), MPI.Comm_size(MPI.COMM_WORLD)), prefix="") -> DRef{Vec{T}}

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

• v::Vector{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.
• prefix is an optional string prefix for VecSetOptionsPrefix() to set vector-specific command-line options.
• Returns a DRef that will destroy the PETSc Vec collectively when all ranks release their reference.

Vec_sum(v::SparseVector{T}; row_partition=default_row_partition(length(v), MPI.Comm_size(MPI.COMM_WORLD)), prefix="", own_rank_only=false) -> DRef{Vec{T}}

Create a distributed PETSc vector by summing sparse vectors across ranks (on MPI.COMM_WORLD).

• v::SparseVector{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.
• prefix is an optional string prefix for VecSetOptionsPrefix() to set vector-specific command-line options.
• own_rank_only::Bool (default=false): if true, asserts that all nonzero indices fall within this rank's row partition.
• Returns a DRef that will destroy the PETSc Vec collectively when all ranks release their reference.

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

zeros_like(x::Vec{T}; T2::Type{S}=T, prefix::String=x.obj.prefix) -> Vec{S}

Create a new distributed vector with the same size and partition as x, filled with zeros.

Arguments

• x: Template vector to match size and partition
• T2: Element type of the result (defaults to same type as x)
• prefix: PETSc options prefix (defaults to same prefix as x)

See also: ones_like, fill_like, Vec_uniform

ones_like(x::Vec{T}; T2::Type{S}=T, prefix::String=x.obj.prefix) -> Vec{S}

Create a new distributed vector with the same size and partition as x, filled with ones.

Arguments

• x: Template vector to match size and partition
• T2: Element type of the result (defaults to same type as x)
• prefix: PETSc options prefix (defaults to same prefix as x)

See also: zeros_like, fill_like, Vec_uniform

fill_like(x::Vec{T}, val; T2::Type{S}=typeof(val), prefix::String=x.obj.prefix) -> Vec{S}

Create a new distributed vector with the same size and partition as x, filled with val.

Arguments

• x: Template vector to match size and partition
• val: Value to fill the vector with
• T2: Element type of the result (defaults to type of val)
• prefix: PETSc options prefix (defaults to same prefix as x)

Example

y = fill_like(x, 3.14)  # Create a vector like x, filled with 3.14

See also: zeros_like, ones_like, Vec_uniform

default_row_partition(n::Int, nranks::Int) -> Vector{Int}

Create a default row partition that divides n rows equally among nranks.

Returns a Vector{Int} of length nranks+1 where partition[i] is the start row (1-indexed) for rank i-1.