GitHub

Vec

PETSc vectors (Vec) are the fundamental building blocks for storing solution data, right-hand sides, and other distributed arrays. PETSc.jl provides a Julia-friendly interface that makes Vec objects behave like native Julia arrays.

Overview

PETSc vectors support:

  • Distributed parallel storage: Split across MPI processes
  • Sequential storage: For serial computations
  • Ghost points: For communication in stencil operations
  • Julia array interface: Use familiar indexing and broadcasting syntax

Creating Vectors

Sequential Vectors

# Create a sequential vector of length n
v = PetscVec(petsclib, n)

# Wrap an existing Julia array (no copy)
julia_array = zeros(100)
v = PetscVec(petsclib, julia_array)

# `destroy!` releases it; a vector on MPI.COMM_SELF also gets a finalizer
PETSc.destroy!(v)

From DM Objects

# Create global and local vectors from a DM
gvec = PETSc.global_vec(dm)
lvec = PETSc.local_vec(dm)

PetscVec replaces v0.4's VecSeq and as_petsc_vec: construction goes through the type (naming conventions, §6). The old spellings still work in v0.5 and warn once.

Julia Array Interface

PETSc vectors implement the Julia array interface:

v[1] = 1.0           # Set single element
v[1:10] .= 2.0       # Set range
x = v[5]             # Get element
length(v)            # Get length
size(v)              # Get size tuple

Assembly

After setting values, vectors must be assembled:

v[1] = 1.0
v[2] = 2.0
PETSc.assemble!(v)  # Finalize vector assembly

Ghost Point Updates

For vectors with ghost points (from DMDA/DMStag):

# Update ghost values from neighboring processes
PETSc.ghost_update!(vec, PETSc.INSERT_VALUES, PETSc.SCATTER_FORWARD)

# Or use begin/end for non-blocking:
PETSc.ghost_update_begin!(vec, PETSc.INSERT_VALUES, PETSc.SCATTER_FORWARD)
# ... do other work ...
PETSc.ghost_update_end!(vec, PETSc.INSERT_VALUES, PETSc.SCATTER_FORWARD)

Functions

PETSc.AbstractPetscMemBackend — Type
AbstractPetscMemBackend

Abstract supertype for GPU memory backends used by PETSc extensions. Host memory is represented by nothing, not a subtype of this. GPU extensions define their own concrete subtype (e.g. CUDAMemBackend).

source
PETSc.LibPETSc.PetscVec — Method
PetscVec(petsclib, ptr::CVec, own::Bool)

Wrap a raw PETSc Vec handle.

own = false is the borrowed case of docs/src/man/naming.md §3.3: no finalizer is attached and destroy! is a no-op. The result is a VecPtr, the wrapper type that carries the ownership flag.

source
PETSc.LibPETSc.PetscVec — Method
PetscVec(v::AbstractPetscVec)

The plain PetscVec handle behind any high-level vector wrapper, borrowed from v: destroy! on it does nothing (see owns).

The autowrapped *AndMemType routines are typed x::PetscVec, while AbstractPetscVec also covers VecPtr; this converts transparently.

source
PETSc.LibPETSc.PetscVec — Method
v = PetscVec(petsclib, comm, array)

Creates a sequential PETSc vector of length n given a julia array array, on the communicator comm. The vector uses array as its storage and keeps it alive.

External Links

source
PETSc.LibPETSc.PetscVec — Method
PetscVec(petsclib, n::Integer)

A standard, sequentially-stored serial PETSc vector for petsclib.PetscScalar of length n.

Replaces v0.4's VecSeq: construction goes through the type (docs/src/man/naming.md §5.1).

External Links

source
PETSc.LibPETSc.PetscVec — Method
PetscVec(petsclib, v::Vector)

A standard, sequentially-stored serial PETSc vector, wrapping the Julia vector v.

This reuses the array v as storage, and so v should not be resize!-ed or otherwise have its length modified while the PETSc object exists. The vector keeps v alive, so PetscVec(petsclib, [1.0, 2.0]) is safe.

This should only be need to be called for more advanced uses, for most simple usecases, users should be able to pass Vectors directly and have the wrapping performed automatically

External Links

source
PETSc.PetscVecStyle — Type
PetscVecStyle

The broadcast style of a PetscVec: an expression with one in it runs on the local arrays rather than entry by entry. It wins over an ordinary Vector, so x .+ v uses it too.

source
PETSc.VecPtr — Type
VecPtr(petsclib, ptr::CVec, own::Bool)

Container type for a PETSc Vec that is just a raw pointer.

If own is true a finalizer is set on the vector, but only on a serial communicator, since VecDestroy is collective and a GC finalizer runs at an arbitrary point. If own is false the handle belongs to PETSc and destroy! is a no-op, leaving the wrapper usable.

source
Base.copyto! — Method
copyto!(dst::AbstractPetscVec, src::AbstractPetscVec)

Copy the entries of src into dst and return dst. The two vectors must have the same global length, which throws a DimensionMismatch otherwise, and the same parallel layout, which PETSc checks.

External Links

source
PETSc.acquire_local_array — Method
acquire_local_array(vec; read, write) -> (arr, cpu_arr, backend)

Get the local array from vec via VecGetArray*AndMemType without registering a Julia finalizer. Returns the user-visible array, the raw PETSc cpuarr needed for restore, and the backend singleton. Extensions overload `makelocalarray(cpuarr, backend)to wrap the raw array for their device (e.g.CUDAMemBackend→CuArray`).

source
PETSc.destroy! — Method
destroy!(v::AbstractPetscVec)

Destroy a PETSc vector and release its resources.

Safe to call more than once, and safe to reach as a GC finalizer after the library has been finalized or re-initialized: see isdestroyable. Does nothing on a vector that only borrows its handle: see owns.

External Links

source
PETSc.ghost_update! — Method
ghost_update!(
    vec::AbstractPetscVec,
    insertmode = INSERT_VALUES,
    scattermode = SCATTER_FORWARD,
)

Finishes scattering vec to the local or global representations

External Links

source
PETSc.ghost_update_end! — Method
ghost_update_end!(
    vec::AbstractPetscVec,
    insertmode = INSERT_VALUES,
    scattermode = SCATTER_FORWARD,
)

Finishes scattering vec to the local or global representations

External Links

source
PETSc.local_arrays — Method
local_arrays(petsclib, g_fx, l_x) -> (fx, lx, fx_arr, lx_arr, fx_bounce)

Return arrays for g_fx (read-write) and l_x (read-only) suitable for passing to a compute kernel. Dispatches on the memory location of each Vec via memtype_backend.

On the pure-CPU path (host × host (both backends nothing)) fx/lx are plain Arrays and fx_arr = lx_arr = fx_bounce = nothing. When a GPU backend extension is loaded and a Vec lives on the device the returned fx/lx are device arrays. An optional bounce buffer fx_bounce is allocated when g_fx is host-resident; its contents must be written back by restore_local_arrays! after the kernel completes.

See also: restore_local_arrays!

source
PETSc.memtype — Method

Query the PetscMemType of each Vec and return the corresponding array type. Errors if the Vecs are on heterogeneous devices (different PetscMemType values), since a single with_local_array! call cannot handle mixed backends. Returns Vector when all Vecs are host-resident.

Extensions overload array_type(::Val{MT}) for a PetscMemType enum value MT to register the corresponding array type (e.g. PETSC_MEMTYPE_DEVICE → CuArray).

source
PETSc.memtype_backend — Method
memtype_backend(mtype::PetscMemType) → Nothing | AbstractPetscMemBackend

Convert a PetscMemType to a dispatch tag. Returns nothing for host memory; GPU extensions return their own singleton for device memory.

source
PETSc.ownership_range — Method
ownership_range(vec::AbstractPetscVec)

The range of indices owned by this processor, assuming that the vec is laid out with the first n1 elements on the first processor, next n2 elements on the second, etc. For certain parallel layouts this range may not be well defined.

The range is 1-based, always: an index into Julia data is 1-based (docs/src/man/naming.md §12.1). v0.4 took base_one::Bool positionally and made the convention a runtime choice; ownership_range(v, false) warns in v0.5 and is a MethodError in v0.6.

Note

unlike the C function, the range returned is inclusive (idx_first:idx_last)

External Links

source
PETSc.release_local_array — Method
release_local_array(cpu_arr, backend, vec; read, write)

Restore a previously acquired local array. Called in finally blocks by with_local_array!. Extensions overload this for GPU backends.

source
PETSc.restore_local_arrays! — Method
restore_local_arrays!(petsclib, g_fx, l_x, fx, lx, fx_arr, lx_arr, fx_bounce)

Restore PETSc Vecs after a kernel launched via local_arrays.

Dispatches to _restore_local_arrays!. On the CPU path (fx_arr, lx_arr, fx_bounce all nothing) this simply finalizes fx and lx, triggering the registered VecRestoreArray*AndMemType finalizers. GPU backend extensions add a _restore_local_arrays! method for their array types.

source
PETSc.type_name — Method
type_name(v::AbstractPetscVec)

The name PETSc knows this vector's implementation by, as a Symbol (:seq, :mpi, …), or nothing when no type has been set yet (docs/src/man/naming.md §3.1). v0.4 answered with a String; that is a break with no shim (§16).

External Links

source
PETSc.unsafe_local_array — Method
unsafe_local_array(vec::AbstractVec; read=true, write=true)

Return an Array{PetscScalar} containing local portion of the PETSc vec

Use read=false if the array is write-only; write=false if read-only.

Note

Base.finalize should be called on the Array before the data can be used.

External Links

source
PETSc.with_local_array! — Method
with_local_array!(
    f!,
    vecs::NTuple{N, AbstractVec};
    read::Union{Bool, NTuple{N, Bool}} = true,
    write::Union{Bool, NTuple{N, Bool}} = true,
)
with_local_array!(::Type{A}, f!, vecs...; read, write) where {A <: AbstractArray}

Apply f! to local array views of vecs.

The optional ::Type{A} second argument (after the do-block function) asserts that every array returned from VecGetArray*AndMemType is of type A. Use it with do-block syntax:

with_local_array!(Vector, petsc_x; write=true) do x
    x .= 1
end
source