# VecScatterCreate

Creates a vector scatter context.

### Synopsis

    #include "petscis.h"
    #include "petscvec.h"
    PetscErrorCode  VecScatterCreate(Vec xin,IS ix,Vec yin,IS iy,VecScatter *newctx)

Collective on Vec

### Input Parameters

| xin | - a vector that defines the shape (parallel data layout of the vector) of vectors from which we scatter
| yin | - a vector that defines the shape (parallel data layout of the vector) of vectors to which we scatter
| ix | - the indices of xin to scatter (if PETSC_NULL scatters all values)
| iy | - the indices of yin to hold results (if PETSC_NULL fills entire vector yin)

### Output Parameter

newctx -location to store the new scatter context

Options Database Keys: (uses regular MPI_Sends by default)

| -vecscatter_ssend | - Uses MPI_Ssend_init() instead of MPI_Send_init()
| -vecscatter_rsend | - use ready receiver mode for MPI sends
| -vecscatter_merge | - VecScatterBegin() handles all of the communication, VecScatterEnd() is a nop eliminates the chance for overlap of computation and communication
| -vecscatter_sendfirst | - Posts sends before receives
| -vecscatter_packtogether | - Pack all messages before sending, receive all messages before unpacking
| -vecscatter_alltoall | - Uses MPI all to all communication for scatter
| -vecscatter_nopack | - Avoid packing to work vector when possible (if used with -vecscatter_alltoall then will use MPI_Alltoallw()

                                                                                       --When packing is used--

                                  MPI Datatypes (no packing)  sendfirst   merge        packtogether  persistent*    -vecscatter_

       Message passing    Send       p                           X            X           X         always

                         Ssend       p                           X            X           X         always          _ssend

                         Rsend       p                        nonsense        X           X         always          _rsend

       AlltoAll  v or w              X                        nonsense     always         X         nonsense        _alltoall

       MPI_Win                       p                        nonsense        p           p         nonsense        _window

                  -vecscatter_     _nopack                   _sendfirst    _merge      _packtogether

                                  $   Since persistent sends and receives require a constant memory address they can only be used when data is packed into the work vector

      because the in and out array may be different for each call to VecScatterBegin/End().

       p indicates possible, but not implemented. X indicates implemented

### C++ variants

| VecScatter VecScatterCreate(Vec x,Vec y,IS is) |  | -> |  | VecScatterCreate(x,PETSC_NULL,y,is,&s); return s;
| VecScatterCreate(Vec x,Vec y,IS is,VecScatter *s) |  | -> |  | VecScatterCreate(x,PETSC_NULL,y,is,s)
| VecScatter VecScatterCreate(Vec x,IS is,Vec y) |  | -> |  | VecScatterCreate(x,is,y,PETSC_NULL,&s); return s;
| VecScatterCreate(Vec x,IS is,Vec y,VecScatter *s) |  | -> |  | VecScatterCreate(x,is,y,PETSC_NULL,s)
| VecScatter VecScatterCreate(Vec x,IS is1,Vec y,IS is2) |  | -> |  | VecScatterCreate(x,is1,y,is2,&s); return s;

### Notes

In calls to VecScatter() 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.

Currently the MPI_Send(), MPI_Ssend() and MPI_Rsend() all use PERSISTENT versions. (this unfortunately requires that the same in and out arrays be used for each use, this is why when no using MPI_alltoallw() we always need to pack the input into the work array before sending and unpack upon recieving instead of using MPI datatypes to avoid the packing/unpacking).

### See Also

VecScatterDestroy(), VecScatterCreateToAll(), VecScatterCreateToZero()

Level:intermediate
Location:src/vec/vec/utils/vscat.c
Index of all Vec routines
Table of Contents for all manual pages
Index of all manual pages

### Examples

src/snes/examples/tutorials/ex33f.F.html
src/dm/ao/examples/tutorials/ex2.c.html
src/dm/da/examples/tutorials/ex6.c.html
src/dm/da/examples/tutorials/ex6f90.F.html