petsc-3.14.5 2021-03-03
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

### 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 NULL scatters all values)
| iy | - the indices of yin to hold results (if NULL fills entire vector yin)

### Output Parameter

| newctx | - 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
| -vecscatter_packtogether | - Pack all messages before sending, receive all messages before unpacking will make the results of scatters deterministic when otherwise they are not (it may be slower also).
| -vecscatter_type sf | - Use the PetscSF implementation of vecscatter (Default). One can use PetscSF options to control the communication.
| -vecscatter_packongpu | - For GPU vectors, pack needed entries on GPU, then copy packed data to CPU, then do MPI. Otherwise, we might copy a segment encompassing needed entries. Default is TRUE.

### 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 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() use PERSISTENT versions. (this unfortunately requires that the same in and out arrays be used for each use, this is why we always need to pack the input into the work array before sending and unpack upon receiving instead of using MPI datatypes to avoid the packing/unpacking).

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 ranks. Use VecScatterCreateToZero() to create a vecscatter that copies an MPI vector to a sequential vector on MPI rank 0. These special vecscatters have better performance than general ones.

### See Also

VecScatterDestroy(), VecScatterCreateToAll(), VecScatterCreateToZero(), PetscSFCreate()

### Level

intermediate

### Location

src/vec/vscat/interface/vscreate.c

### Examples

src/vec/vec/utils/tagger/tutorials/ex1.c.html
src/dm/tutorials/ex6.c.html
src/ksp/ksp/tutorials/ex49.c.html
src/ksp/ksp/tutorials/ex73.c.html
src/tao/pde_constrained/tutorials/elliptic.c.html
src/tao/pde_constrained/tutorials/parabolic.c.html
src/tao/pde_constrained/tutorials/hyperbolic.c.html

### Implementations

VecScatterCreate_MPI1 in src/vec/vscat/impls/mpi1/vpscat_mpi1.c
VecScatterCreate_MPI3 in src/vec/vscat/impls/mpi3/vpscat.c
VecScatterCreate_MPI3Node in src/vec/vscat/impls/mpi3/vpscat.c
VecScatterCreate_Seq in src/vec/vscat/impls/seq/seqvscat.c
VecScatterCreate_SF in src/vec/vscat/impls/sf/vscatsf.c
VecScatterCreate_PtoS(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptos) in src/vec/vscat/impls/vscat.c
VecScatterCreate_PtoP(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptop) in src/vec/vscat/impls/vscat.c
Index of all Vec routines
Table of Contents for all manual pages
Index of all manual pages