Skip to main content
`Ctrl`+`K`

# VecScatterCreate

Creates a vector scatter `VecScatter` context that is used to communicate entries between two vectors `Vec`

## Synopsis

    #include "petscsf.h"
    PetscErrorCode VecScatterCreate(Vec x, IS ix, Vec y, IS iy, VecScatter *newsf)

Collective

## Input Parameters

- x - a vector that defines the shape (parallel data layout of the vector) of vectors from which we scatter

- y - a vector that defines the shape (parallel data layout of the vector) of vectors to which we scatter

- ix - the indices of `x` to scatter (if `NULL` scatters all values)

- iy - the indices of `y` to hold results (if `NULL` fills entire vector `yin` in order)

## Output Parameter

- newsf - location to store the new scatter context

## Options Database Keys

- -vecscatter_view - Prints detail of communications

- -vecscatter_view ::ascii_info - Print less details about communication

- -vecscatter_merge - `VecScatterBegin()` handles all of the communication, `VecScatterEnd()` is a nop eliminates the chance for overlap of computation and communication

## Notes

If both `xin` and `yin` are parallel, their communicator must be on the same set of processes, but their process order can be different. In calls to the scatter options you can use different vectors than the `xin` and `yin` you used above; BUT they must have the same parallel data layout, for example, they could be obtained from `VecDuplicate()`. A `VecScatter` context CANNOT be used in two or more simultaneous scatters; that is you cannot call a second `VecScatterBegin()` with the same scatter context until the `VecScatterEnd()` has been called on the first `VecScatterBegin()`. In this case a separate `VecScatter` is needed for each concurrent scatter.

Both `ix` and `iy` cannot be `NULL` at the same time.

Use `VecScatterCreateToAll()` to create a `VecScatter` that copies an MPI vector to sequential vectors on all MPI processes. Use `VecScatterCreateToZero()` to create a `VecScatter` that copies an MPI vector to a sequential vector on MPI rank 0. These special `VecScatter` have better performance than general ones.

## Developer Note

The implementations of most the `VecScatter` are done using `PetscSF`.

## See Also

Low-level Vector Communication, `VecScatter`, `VecScatterDestroy()`, `VecScatterCreateToAll()`, `VecScatterCreateToZero()`, `PetscSFCreate()`, `VecScatterType`, `InsertMode`, `ScatterMode`, `VecScatterBegin()`, `VecScatterEnd()`

## Level

intermediate

## Location

src/vec/is/sf/interface/vscat.c

## Examples

src/dm/tutorials/ex22.c
src/ts/tutorials/ex30.c
src/ksp/ksp/tutorials/ex73.c
src/tao/pde_constrained/tutorials/parabolic.c
src/dm/tutorials/ex6.c
src/ksp/ksp/tutorials/ex49.c
src/tao/pde_constrained/tutorials/hyperbolic.c
src/tao/pde_constrained/tutorials/elliptic.c
src/vec/vec/tutorials/ex44.c
src/dm/tutorials/ex14.c

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