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 = VecSeq(petsclib, n)

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

From DM Objects

# Create global and local vectors from a DM
global_vec = DMGlobalVec(dm)
local_vec = DMLocalVec(dm)

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
assemble!(v)  # Finalize vector assembly

Ghost Point Updates

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

# Update ghost values from neighboring processes
ghostupdate!(vec, INSERT_VALUES, SCATTER_FORWARD)

# Or use begin/end for non-blocking:
ghostupdatebegin!(vec, INSERT_VALUES, SCATTER_FORWARD)
# ... do other work ...
ghostupdateend!(vec, INSERT_VALUES, 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.VecPtr — Type
VecPtr(petsclib, ptr::CVec, own::Bool)

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

If own is true, the finalizer is set on the vector; calling destroy when own is false is a no-op.

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

Creates a sequential PETSc vector of length n given a julia array array`

source
PETSc.VecSeq — Method
VecSeq(petsclib, n::Int)

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

External Links

source
PETSc.VecSeq — Method
VecSeq(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.

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.acquire_petsc_local_array — Method
acquire_petsc_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.determine_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 withlocalarray! 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.get_petsc_arrays — Method
get_petsc_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_petsc_arrays after the kernel completes.

See also: restore_petsc_arrays

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

Finishes scattering vec to the local or global representations

External Links

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

Finishes scattering vec to the local or global representations

External Links

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.ownershiprange — Method
ownershiprange(vec::AbstractVec, [base_one = true])

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.

If the optional argument base_one == true then base-1 indexing is used, otherwise base-0 index is used.

Note

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

External Links

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

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

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

Restore PETSc Vecs after a kernel launched via get_petsc_arrays.

Dispatches to restore_petsc_arrays_impl. 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_petsc_arrays_impl method for their array types.

source
PETSc.unsafe_localarray — Method
unsafe_localarray(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.withlocalarray! — Method
withlocalarray!(
    f!,
    vecs::NTuple{N, AbstractVec};
    read::Union{Bool, NTuple{N, Bool}} = true,
    write::Union{Bool, NTuple{N, Bool}} = true,
)
withlocalarray!(::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:

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