VecScatterBegin — PETSc 3.25.0 documentation

Skip to main content
`Ctrl`+`K`

# VecScatterBegin

Begins a generalized scatter from one vector to another. Complete the scattering phase with `VecScatterEnd()`.

## Synopsis

    #include "petscsf.h"
    PetscErrorCode VecScatterBegin(VecScatter sf, Vec x, Vec y, InsertMode addv, ScatterMode mode)

Neighbor-wise Collective

## Input Parameters

- sf - scatter context generated by `VecScatterCreate()`

- x - the vector from which we scatter

- y - the vector to which we scatter

- addv - either `ADD_VALUES`, `MAX_VALUES`, `MIN_VALUES` or `INSERT_VALUES`, with `INSERT_VALUES` mode any location not scattered to retains its old value; i.e. the vector is NOT first zeroed.

- mode - the scattering mode, usually `SCATTER_FORWARD`. The available modes are: `SCATTER_FORWARD` or `SCATTER_REVERSE`

## Notes

The vectors `x` and `y` need not be the same vectors used in the call to `VecScatterCreate()`, but `x` must have the same parallel data layout as that passed in as the `x` to `VecScatterCreate()`, similarly for the `y`. Most likely they have been obtained from `VecDuplicate()`.

You cannot change the values in the input vector between the calls to `VecScatterBegin()` and `VecScatterEnd()`.

If you use `SCATTER_REVERSE` the two arguments `x` and `y` should be reversed, from the `SCATTER_FORWARD`.

      y[iy[i]] = x[ix[i]], for i=0,...,ni-1

This scatter is far more general than the conventional scatter, since it can be a gather or a scatter or a combination, depending on the indices ix and iy. If x is a parallel vector and y is sequential, `VecScatterBegin()` can serve to gather values to a single processor. Similarly, if `y` is parallel and `x` sequential, the routine can scatter from one processor to many processors.

## See Also

Low-level Vector Communication, `VecScatter`, `VecScatterCreate()`, `VecScatterEnd()`, `InsertMode`, `ScatterMode`

## Level

intermediate

## Location

src/vec/vec/utils/vscat.c

## Examples

src/dm/tutorials/ex25.c
src/tao/constrained/tutorials/ex1.c
src/tao/pde_constrained/tutorials/hyperbolic.c
src/ksp/ksp/tutorials/ex43.c
src/ksp/ksp/tutorials/ex73.c
src/ksp/ksp/tutorials/ex49.c
src/dm/tutorials/ex22.c
src/tao/pde_constrained/tutorials/elliptic.c
src/dm/tutorials/ex14.c
src/dm/tutorials/ex6.c

Index of all Vec routines
Table of Contents for all manual pages
Index of all manual pages