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

Convert x to an Array{PetscScalar} using unsafe_localarray and apply the function f!.

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

Examples

julia> withlocalarray!(x; write=true) do x
   @. x .*= 2
end

julia> withlocalarray!(
           x,
           y;
           read = (false, true),
           write = (true, false)
       ) do x, y
   @. x .= 2 .+ y
end
Note

Base.finalize is automatically called on the array.

source