1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecScatterCreate.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>VecScatterCreate</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>petsc-3.14.5 2021-03-03</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.14.5 v3.14.5 docs/manualpages/Vec/VecScatterCreate.html "><small>Report Typos and Errors</small></a></div>
<A NAME="VecScatterCreate"><H1>VecScatterCreate</H1></A>
Creates a vector scatter context.
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscvec.h"
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../Vec/VecScatterCreate.html#VecScatterCreate">VecScatterCreate</A>(<A HREF="../Vec/Vec.html#Vec">Vec</A> xin,<A HREF="../IS/IS.html#IS">IS</A> ix,<A HREF="../Vec/Vec.html#Vec">Vec</A> yin,<A HREF="../IS/IS.html#IS">IS</A> iy,<A HREF="../Vec/VecScatter.html#VecScatter">VecScatter</A> *newctx)
</PRE>
Collective on <A HREF="../Vec/Vec.html#Vec">Vec</A>
<P>
<H3><FONT COLOR="#CC3333">Input Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>xin </B></TD><TD>- a vector that defines the shape (parallel data layout of the vector)
of vectors from which we scatter
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>yin </B></TD><TD>- a vector that defines the shape (parallel data layout of the vector)
of vectors to which we scatter
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>ix </B></TD><TD>- the indices of xin to scatter (if NULL scatters all values)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>iy </B></TD><TD>- the indices of yin to hold results (if NULL fills entire vector yin)
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Output Parameter</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>newctx </B></TD><TD>- location to store the new scatter context
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Options Database Keys</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_view </B></TD><TD>- Prints detail of communications
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_view ::ascii_info </B></TD><TD>- Print less details about communication
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_merge </B></TD><TD>- <A HREF="../Vec/VecScatterBegin.html#VecScatterBegin">VecScatterBegin</A>() handles all of the communication, <A HREF="../Vec/VecScatterEnd.html#VecScatterEnd">VecScatterEnd</A>() is a nop
eliminates the chance for overlap of computation and communication
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_packtogether </B></TD><TD>- 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).
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_type sf </B></TD><TD>- Use the <A HREF="../PetscSF/PetscSF.html#PetscSF">PetscSF</A> implementation of vecscatter (Default). One can use <A HREF="../PetscSF/PetscSF.html#PetscSF">PetscSF</A> options to control the communication.
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-vecscatter_packongpu </B></TD><TD>- 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.
</TD></TR></TABLE>
<P>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
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 <A HREF="../Vec/VecScatter.html#VecScatter">VecScatter</A>() 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 <A HREF="../Vec/VecDuplicate.html#VecDuplicate">VecDuplicate</A>().
A <A HREF="../Vec/VecScatter.html#VecScatter">VecScatter</A> context CANNOT be used in two or more simultaneous scatters;
that is you cannot call a second <A HREF="../Vec/VecScatterBegin.html#VecScatterBegin">VecScatterBegin</A>() with the same scatter
context until the <A HREF="../Vec/VecScatterEnd.html#VecScatterEnd">VecScatterEnd</A>() has been called on the first <A HREF="../Vec/VecScatterBegin.html#VecScatterBegin">VecScatterBegin</A>().
In this case a separate <A HREF="../Vec/VecScatter.html#VecScatter">VecScatter</A> is needed for each concurrent scatter.
<P>
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).
<P>
Both ix and iy cannot be NULL at the same time.
<P>
Use <A HREF="../Vec/VecScatterCreateToAll.html#VecScatterCreateToAll">VecScatterCreateToAll</A>() to create a vecscatter that copies an MPI vector to sequential vectors on all MPI ranks.
Use <A HREF="../Vec/VecScatterCreateToZero.html#VecScatterCreateToZero">VecScatterCreateToZero</A>() 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.
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../Vec/VecScatterDestroy.html#VecScatterDestroy">VecScatterDestroy</A>(), <A HREF="../Vec/VecScatterCreateToAll.html#VecScatterCreateToAll">VecScatterCreateToAll</A>(), <A HREF="../Vec/VecScatterCreateToZero.html#VecScatterCreateToZero">VecScatterCreateToZero</A>(), <A HREF="../PetscSF/PetscSFCreate.html#PetscSFCreate">PetscSFCreate</A>()
<BR><P><B></B><H3><FONT COLOR="#CC3333">Level</FONT></H3>intermediate<BR>
<H3><FONT COLOR="#CC3333">Location</FONT></H3>
</B><A HREF="../../../src/vec/vscat/interface/vscreate.c.html#VecScatterCreate">src/vec/vscat/interface/vscreate.c</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/vec/vec/utils/tagger/tutorials/ex1.c.html">src/vec/vec/utils/tagger/tutorials/ex1.c.html</A><BR>
<A HREF="../../../src/dm/tutorials/ex6.c.html">src/dm/tutorials/ex6.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/tutorials/ex49.c.html">src/ksp/ksp/tutorials/ex49.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/tutorials/ex73.c.html">src/ksp/ksp/tutorials/ex73.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/tutorials/elliptic.c.html">src/tao/pde_constrained/tutorials/elliptic.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/tutorials/parabolic.c.html">src/tao/pde_constrained/tutorials/parabolic.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/tutorials/hyperbolic.c.html">src/tao/pde_constrained/tutorials/hyperbolic.c.html</A><BR>
<P><H3><FONT COLOR="CC3333">Implementations</FONT></H3><A HREF="../../../src/vec/vscat/impls/mpi1/vpscat_mpi1.c.html#VecScatterCreate_MPI1">VecScatterCreate_MPI1 in src/vec/vscat/impls/mpi1/vpscat_mpi1.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/mpi3/vpscat.c.html#VecScatterCreate_MPI3">VecScatterCreate_MPI3 in src/vec/vscat/impls/mpi3/vpscat.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/mpi3/vpscat.c.html#VecScatterCreate_MPI3Node">VecScatterCreate_MPI3Node in src/vec/vscat/impls/mpi3/vpscat.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/seq/seqvscat.c.html#VecScatterCreate_Seq">VecScatterCreate_Seq in src/vec/vscat/impls/seq/seqvscat.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/sf/vscatsf.c.html#VecScatterCreate_SF">VecScatterCreate_SF in src/vec/vscat/impls/sf/vscatsf.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/vscat.c.html#VecScatterCreate_PtoS(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptos)">VecScatterCreate_PtoS(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptos) in src/vec/vscat/impls/vscat.c</A><BR>
<A HREF="../../../src/vec/vscat/impls/vscat.c.html#VecScatterCreate_PtoP(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptop)">VecScatterCreate_PtoP(VecScatter ctx,PetscErrorCode (*vecscattercreatelocal_ptop) in src/vec/vscat/impls/vscat.c</A><BR>
<BR><A HREF="./index.html">Index of all Vec routines</A>
<BR><A HREF="../../index.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
</BODY></HTML>
|
