petsc-3.7.1 2016-05-15
Report Typos and Errors

# VecScatterCreate

Creates a vector scatter context.

### Synopsis

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

Collective on Vec Many br

### Input Parameters

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

### Output Parameter

newctx -location to store the new scatter context Many br

Options Database Keys: (uses regular MPI_Sends by default) Many br

| -vecscatter_view | - Prints detail of communications Many br
| -vecscatter_view ::ascii_info | - Print less details about communication Many br
| -vecscatter_ssend | - Uses MPI_Ssend_init() instead of MPI_Send_init() Many br
| -vecscatter_rsend | - use ready receiver mode for MPI sends Many br
| -vecscatter_merge | - VecScatterBegin() handles all of the communication, VecScatterEnd() is a nop Many breliminates the chance for overlap of computation and communication Many br
| -vecscatter_sendfirst | - Posts sends before receives Many br
| -vecscatter_packtogether | - Pack all messages before sending, receive all messages before unpacking Many br
| -vecscatter_alltoall | - Uses MPI all to all communication for scatter Many br
| -vecscatter_window | - Use MPI 2 window operations to move data Many br
| -vecscatter_nopack | - Avoid packing to work vector when possible (if used with -vecscatter_alltoall then will use MPI_Alltoallw() Many br
| -vecscatter_reproduce | - insure that the order of the communications are done the same for each scatter, this under certain circumstances Many brwill make the results of scatters deterministic when otherwise they are not (it may be slower also). Many br

                                                                                       --When packing is used--

                                  MPI Datatypes (no packing)  sendfirst   merge        packtogether  persistent*

                                   _nopack                   _sendfirst    _merge      _packtogether                -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

      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

Many br

### Notes

In calls to VecScatter() you can use different vectors than the xin and Many bryin you used above; BUT they must have the same parallel data layout, for example, Many brthey could be obtained from VecDuplicate(). Many brA VecScatter context CANNOT be used in two or more simultaneous scatters; Many brthat is you cannot call a second VecScatterBegin() with the same scatter Many brcontext until the VecScatterEnd() has been called on the first VecScatterBegin(). Many brIn this case a separate VecScatter is needed for each concurrent scatter. Many br

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

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

### 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/ksp/ksp/examples/tutorials/ex49.c.html
src/snes/examples/tutorials/ex74f.F90.html
src/tao/pde_constrained/examples/tutorials/elliptic.c.html
src/tao/pde_constrained/examples/tutorials/parabolic.c.html
src/tao/pde_constrained/examples/tutorials/hyperbolic.c.html