xref: /petsc/include/petscvec.h (revision 4e278199b78715991f5c71ebbd945c1489263e6c) 
1 /*
2     Defines the vector component of PETSc. Vectors generally represent
3   degrees of freedom for finite element/finite difference functions
4   on a grid. They have more mathematical structure then simple arrays.
5 */
6 
7 #if !defined(PETSCVEC_H)
8 #define PETSCVEC_H
9 #include <petscsys.h>
10 #include <petscsftypes.h> /* for VecScatter, VecScatterType */
11 #include <petscis.h>
12 #include <petscviewer.h>
13 
14 /*S
15      Vec - Abstract PETSc vector object
16 
17    Level: beginner
18 
19 .seealso:  VecCreate(), VecType, VecSetType()
20 S*/
21 typedef struct _p_Vec*         Vec;
22 
23 /*E
24   ScatterMode - Determines the direction of a scatter
25 
26   Level: beginner
27 
28 .seealso: VecScatter, VecScatterBegin(), VecScatterEnd()
29 E*/
30 typedef enum {SCATTER_FORWARD=0, SCATTER_REVERSE=1, SCATTER_FORWARD_LOCAL=2, SCATTER_REVERSE_LOCAL=3, SCATTER_LOCAL=2} ScatterMode;
31 
32 /*MC
33     SCATTER_FORWARD - Scatters the values as dictated by the VecScatterCreate() call
34 
35     Level: beginner
36 
37 .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
38           SCATTER_REVERSE_LOCAL
39 
40 M*/
41 
42 /*MC
43     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
44          in the VecScatterCreate()
45 
46     Level: beginner
47 
48 .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
49           SCATTER_REVERSE_LOCAL
50 
51 M*/
52 
53 /*MC
54     SCATTER_FORWARD_LOCAL - Scatters the values as dictated by the VecScatterCreate() call except NO parallel communication
55        is done. Any variables that have be moved between processes are ignored
56 
57     Level: developer
58 
59 .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
60           SCATTER_REVERSE_LOCAL
61 
62 M*/
63 
64 /*MC
65     SCATTER_REVERSE_LOCAL - Moves the values in the opposite direction then the directions indicated in
66          in the VecScatterCreate()  except NO parallel communication
67        is done. Any variables that have be moved between processes are ignored
68 
69     Level: developer
70 
71 .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
72           SCATTER_REVERSE
73 
74 M*/
75 
76 /*J
77     VecType - String with the name of a PETSc vector
78 
79    Level: beginner
80 
81 .seealso: VecSetType(), Vec, VecCreate(), VecDestroy()
82 J*/
83 typedef const char* VecType;
84 #define VECSEQ         "seq"
85 #define VECMPI         "mpi"
86 #define VECSTANDARD    "standard"   /* seq on one process and mpi on several */
87 #define VECSHARED      "shared"
88 #define VECSEQVIENNACL "seqviennacl"
89 #define VECMPIVIENNACL "mpiviennacl"
90 #define VECVIENNACL    "viennacl"   /* seqviennacl on one process and mpiviennacl on several */
91 #define VECSEQCUDA     "seqcuda"
92 #define VECMPICUDA     "mpicuda"
93 #define VECCUDA        "cuda"       /* seqcuda on one process and mpicuda on several */
94 #define VECSEQHIP      "seqhip"
95 #define VECMPIHIP      "mpihip"
96 #define VECHIP         "hip"       /* seqcuda on one process and mpicuda on several */
97 #define VECNEST        "nest"
98 #define VECSEQKOKKOS   "seqkokkos"
99 #define VECMPIKOKKOS   "mpikokkos"
100 #define VECKOKKOS      "kokkos"     /* seqkokkos on one process and mpikokkos on several */
101 
102 /* Dynamic creation and loading functions */
103 PETSC_EXTERN PetscErrorCode VecScatterSetType(VecScatter, VecScatterType);
104 PETSC_EXTERN PetscErrorCode VecScatterGetType(VecScatter, VecScatterType*);
105 PETSC_EXTERN PetscErrorCode VecScatterSetFromOptions(VecScatter);
106 PETSC_EXTERN PetscErrorCode VecScatterRegister(const char[],PetscErrorCode (*)(VecScatter));
107 PETSC_EXTERN PetscErrorCode VecScatterCreate(Vec,IS,Vec,IS,VecScatter*);
108 
109 /* Logging support */
110 #define    REAL_FILE_CLASSID 1211213
111 #define    VEC_FILE_CLASSID 1211214
112 PETSC_EXTERN PetscClassId VEC_CLASSID;
113 PETSC_EXTERN PetscClassId PETSCSF_CLASSID;
114 
115 PETSC_EXTERN PetscErrorCode VecInitializePackage(void);
116 PETSC_EXTERN PetscErrorCode VecFinalizePackage(void);
117 
118 PETSC_EXTERN PetscErrorCode VecCreate(MPI_Comm,Vec*);
119 PETSC_EXTERN PetscErrorCode VecCreateSeq(MPI_Comm,PetscInt,Vec*);
120 PETSC_EXTERN PetscErrorCode VecCreateMPI(MPI_Comm,PetscInt,PetscInt,Vec*);
121 PETSC_EXTERN PetscErrorCode VecCreateSeqWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar[],Vec*);
122 PETSC_EXTERN PetscErrorCode VecCreateMPIWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar[],Vec*);
123 PETSC_EXTERN PetscErrorCode VecCreateShared(MPI_Comm,PetscInt,PetscInt,Vec*);
124 PETSC_EXTERN PetscErrorCode VecCreateNode(MPI_Comm,PetscInt,PetscInt,Vec*);
125 
126 PETSC_EXTERN PetscErrorCode VecSetFromOptions(Vec);
127 PETSC_EXTERN PetscErrorCode VecViewFromOptions(Vec,PetscObject,const char[]);
128 
129 PETSC_EXTERN PetscErrorCode VecSetUp(Vec);
130 PETSC_EXTERN PetscErrorCode VecDestroy(Vec*);
131 PETSC_EXTERN PetscErrorCode VecZeroEntries(Vec);
132 PETSC_EXTERN PetscErrorCode VecSetOptionsPrefix(Vec,const char[]);
133 PETSC_EXTERN PetscErrorCode VecAppendOptionsPrefix(Vec,const char[]);
134 PETSC_EXTERN PetscErrorCode VecGetOptionsPrefix(Vec,const char*[]);
135 
136 PETSC_EXTERN PetscErrorCode VecSetSizes(Vec,PetscInt,PetscInt);
137 
138 PETSC_EXTERN PetscErrorCode VecDotNorm2(Vec,Vec,PetscScalar*,PetscReal*);
139 PETSC_EXTERN PetscErrorCode VecDot(Vec,Vec,PetscScalar*);
140 PETSC_EXTERN PetscErrorCode VecDotRealPart(Vec,Vec,PetscReal*);
141 PETSC_EXTERN PetscErrorCode VecTDot(Vec,Vec,PetscScalar*);
142 PETSC_EXTERN PetscErrorCode VecMDot(Vec,PetscInt,const Vec[],PetscScalar[]);
143 PETSC_EXTERN PetscErrorCode VecMTDot(Vec,PetscInt,const Vec[],PetscScalar[]);
144 PETSC_EXTERN PetscErrorCode VecGetSubVector(Vec,IS,Vec*);
145 PETSC_EXTERN PetscErrorCode VecRestoreSubVector(Vec,IS,Vec*);
146 PETSC_EXTERN PetscErrorCode VecConcatenate(PetscInt,const Vec[],Vec*,IS*[]);
147 
148 /*E
149     NormType - determines what type of norm to compute
150 
151     Level: beginner
152 
153 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
154 E*/
155 typedef enum {NORM_1=0,NORM_2=1,NORM_FROBENIUS=2,NORM_INFINITY=3,NORM_1_AND_2=4} NormType;
156 PETSC_EXTERN const char *const NormTypes[];
157 #define NORM_MAX NORM_INFINITY
158 
159 /*MC
160      NORM_1 - the one norm, ||v|| = sum_i | v_i |. ||A|| = max_j || v_*j ||, maximum column sum
161 
162    Level: beginner
163 
164 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_2, NORM_FROBENIUS,
165            NORM_INFINITY, NORM_1_AND_2
166 
167 M*/
168 
169 /*MC
170      NORM_2 - the two norm, ||v|| = sqrt(sum_i |v_i|^2) (vectors only)
171 
172    Level: beginner
173 
174 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_FROBENIUS,
175            NORM_INFINITY, NORM_1_AND_2
176 
177 M*/
178 
179 /*MC
180      NORM_FROBENIUS - ||A|| = sqrt(sum_ij |A_ij|^2), same as NORM_2 for vectors
181 
182    Level: beginner
183 
184 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
185            NORM_INFINITY, NORM_1_AND_2
186 
187 M*/
188 
189 /*MC
190      NORM_INFINITY - ||v|| = max_i |v_i|. ||A|| = max_i || v_i* ||, maximum row sum
191 
192    Level: beginner
193 
194 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
195            NORM_FROBENIUS, NORM_1_AND_2
196 
197 M*/
198 
199 /*MC
200      NORM_1_AND_2 - computes both the 1 and 2 norm of a vector
201 
202    Level: beginner
203 
204 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
205            NORM_FROBENIUS, NORM_INFINITY
206 
207 M*/
208 
209 /*MC
210      NORM_MAX - see NORM_INFINITY
211 
212    Level: beginner
213 
214 M*/
215 
216 PETSC_EXTERN PetscErrorCode VecNorm(Vec,NormType,PetscReal *);
217 PETSC_EXTERN PetscErrorCode VecNormAvailable(Vec,NormType,PetscBool *,PetscReal *);
218 PETSC_EXTERN PetscErrorCode VecNormalize(Vec,PetscReal *);
219 PETSC_EXTERN PetscErrorCode VecSum(Vec,PetscScalar*);
220 PETSC_EXTERN PetscErrorCode VecMax(Vec,PetscInt*,PetscReal *);
221 PETSC_EXTERN PetscErrorCode VecMin(Vec,PetscInt*,PetscReal *);
222 PETSC_EXTERN PetscErrorCode VecScale(Vec,PetscScalar);
223 PETSC_EXTERN PetscErrorCode VecCopy(Vec,Vec);
224 PETSC_EXTERN PetscErrorCode VecSetRandom(Vec,PetscRandom);
225 PETSC_EXTERN PetscErrorCode VecSet(Vec,PetscScalar);
226 PETSC_EXTERN PetscErrorCode VecSetInf(Vec);
227 PETSC_EXTERN PetscErrorCode VecSwap(Vec,Vec);
228 PETSC_EXTERN PetscErrorCode VecAXPY(Vec,PetscScalar,Vec);
229 PETSC_EXTERN PetscErrorCode VecAXPBY(Vec,PetscScalar,PetscScalar,Vec);
230 PETSC_EXTERN PetscErrorCode VecMAXPY(Vec,PetscInt,const PetscScalar[],Vec[]);
231 PETSC_EXTERN PetscErrorCode VecAYPX(Vec,PetscScalar,Vec);
232 PETSC_EXTERN PetscErrorCode VecWAXPY(Vec,PetscScalar,Vec,Vec);
233 PETSC_EXTERN PetscErrorCode VecAXPBYPCZ(Vec,PetscScalar,PetscScalar,PetscScalar,Vec,Vec);
234 PETSC_EXTERN PetscErrorCode VecPointwiseMax(Vec,Vec,Vec);
235 PETSC_EXTERN PetscErrorCode VecPointwiseMaxAbs(Vec,Vec,Vec);
236 PETSC_EXTERN PetscErrorCode VecPointwiseMin(Vec,Vec,Vec);
237 PETSC_EXTERN PetscErrorCode VecPointwiseMult(Vec,Vec,Vec);
238 PETSC_EXTERN PetscErrorCode VecPointwiseDivide(Vec,Vec,Vec);
239 PETSC_EXTERN PetscErrorCode VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
240 PETSC_EXTERN PetscErrorCode VecShift(Vec,PetscScalar);
241 PETSC_EXTERN PetscErrorCode VecReciprocal(Vec);
242 PETSC_EXTERN PetscErrorCode VecPermute(Vec, IS, PetscBool);
243 PETSC_EXTERN PetscErrorCode VecSqrtAbs(Vec);
244 PETSC_EXTERN PetscErrorCode VecLog(Vec);
245 PETSC_EXTERN PetscErrorCode VecExp(Vec);
246 PETSC_EXTERN PetscErrorCode VecAbs(Vec);
247 PETSC_EXTERN PetscErrorCode VecDuplicate(Vec,Vec*);
248 PETSC_EXTERN PetscErrorCode VecDuplicateVecs(Vec,PetscInt,Vec*[]);
249 PETSC_EXTERN PetscErrorCode VecDestroyVecs(PetscInt, Vec*[]);
250 PETSC_EXTERN PetscErrorCode VecStrideNormAll(Vec,NormType,PetscReal[]);
251 PETSC_EXTERN PetscErrorCode VecStrideMaxAll(Vec,PetscInt [],PetscReal []);
252 PETSC_EXTERN PetscErrorCode VecStrideMinAll(Vec,PetscInt [],PetscReal []);
253 PETSC_EXTERN PetscErrorCode VecStrideScaleAll(Vec,const PetscScalar[]);
254 PETSC_EXTERN PetscErrorCode VecUniqueEntries(Vec,PetscInt*,PetscScalar**);
255 
256 PETSC_EXTERN PetscErrorCode VecStrideNorm(Vec,PetscInt,NormType,PetscReal*);
257 PETSC_EXTERN PetscErrorCode VecStrideMax(Vec,PetscInt,PetscInt *,PetscReal *);
258 PETSC_EXTERN PetscErrorCode VecStrideMin(Vec,PetscInt,PetscInt *,PetscReal *);
259 PETSC_EXTERN PetscErrorCode VecStrideScale(Vec,PetscInt,PetscScalar);
260 PETSC_EXTERN PetscErrorCode VecStrideSet(Vec,PetscInt,PetscScalar);
261 
262 PETSC_EXTERN PetscErrorCode VecStrideGather(Vec,PetscInt,Vec,InsertMode);
263 PETSC_EXTERN PetscErrorCode VecStrideScatter(Vec,PetscInt,Vec,InsertMode);
264 PETSC_EXTERN PetscErrorCode VecStrideGatherAll(Vec,Vec[],InsertMode);
265 PETSC_EXTERN PetscErrorCode VecStrideScatterAll(Vec[],Vec,InsertMode);
266 
267 PETSC_EXTERN PetscErrorCode VecStrideSubSetScatter(Vec,PetscInt,const PetscInt[],const PetscInt[],Vec,InsertMode);
268 PETSC_EXTERN PetscErrorCode VecStrideSubSetGather(Vec,PetscInt,const PetscInt[],const PetscInt[],Vec,InsertMode);
269 
270 PETSC_EXTERN PetscErrorCode VecSetValues(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
271 PETSC_EXTERN PetscErrorCode VecGetValues(Vec,PetscInt,const PetscInt[],PetscScalar[]);
272 PETSC_EXTERN PetscErrorCode VecAssemblyBegin(Vec);
273 PETSC_EXTERN PetscErrorCode VecAssemblyEnd(Vec);
274 PETSC_EXTERN PetscErrorCode VecStashSetInitialSize(Vec,PetscInt,PetscInt);
275 PETSC_EXTERN PetscErrorCode VecStashView(Vec,PetscViewer);
276 PETSC_EXTERN PetscErrorCode VecStashViewFromOptions(Vec,PetscObject,const char[]);
277 PETSC_EXTERN PetscErrorCode VecStashGetInfo(Vec,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
278 
279 /*MC
280    VecSetValue - Set a single entry into a vector.
281 
282    Synopsis:
283    #include <petscvec.h>
284    PetscErrorCode VecSetValue(Vec v,PetscInt row,PetscScalar value, InsertMode mode);
285 
286    Not Collective
287 
288    Input Parameters:
289 +  v - the vector
290 .  row - the row location of the entry
291 .  value - the value to insert
292 -  mode - either INSERT_VALUES or ADD_VALUES
293 
294    Notes:
295    For efficiency one should use VecSetValues() and set several or
296    many values simultaneously if possible.
297 
298    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
299    MUST be called after all calls to VecSetValue() have been completed.
300 
301    VecSetValue() uses 0-based indices in Fortran as well as in C.
302 
303    Level: beginner
304 
305 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
306 M*/
307 PETSC_STATIC_INLINE PetscErrorCode VecSetValue(Vec v,PetscInt i,PetscScalar va,InsertMode mode) {return VecSetValues(v,1,&i,&va,mode);}
308 
309 PETSC_EXTERN PetscErrorCode VecSetBlockSize(Vec,PetscInt);
310 PETSC_EXTERN PetscErrorCode VecGetBlockSize(Vec,PetscInt*);
311 PETSC_EXTERN PetscErrorCode VecSetValuesBlocked(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
312 
313 /* Dynamic creation and loading functions */
314 PETSC_EXTERN PetscFunctionList VecList;
315 PETSC_EXTERN PetscErrorCode VecSetType(Vec,VecType);
316 PETSC_EXTERN PetscErrorCode VecGetType(Vec,VecType*);
317 PETSC_EXTERN PetscErrorCode VecRegister(const char[],PetscErrorCode (*)(Vec));
318 
319 PETSC_EXTERN PetscErrorCode VecScatterBegin(VecScatter,Vec,Vec,InsertMode,ScatterMode);
320 PETSC_EXTERN PetscErrorCode VecScatterEnd(VecScatter,Vec,Vec,InsertMode,ScatterMode);
321 PETSC_EXTERN PetscErrorCode VecScatterDestroy(VecScatter*);
322 PETSC_EXTERN PetscErrorCode VecScatterSetUp(VecScatter);
323 PETSC_EXTERN PetscErrorCode VecScatterCopy(VecScatter,VecScatter *);
324 PETSC_EXTERN PetscErrorCode VecScatterView(VecScatter,PetscViewer);
325 PETSC_EXTERN PetscErrorCode VecScatterViewFromOptions(VecScatter,PetscObject,const char[]);
326 PETSC_EXTERN PetscErrorCode VecScatterRemap(VecScatter,PetscInt[],PetscInt[]);
327 PETSC_EXTERN PetscErrorCode VecScatterGetMerged(VecScatter,PetscBool*);
328 
329 PETSC_EXTERN PetscErrorCode VecGetArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
330 PETSC_EXTERN PetscErrorCode VecRestoreArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
331 PETSC_EXTERN PetscErrorCode VecGetArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
332 PETSC_EXTERN PetscErrorCode VecRestoreArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
333 PETSC_EXTERN PetscErrorCode VecGetArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
334 PETSC_EXTERN PetscErrorCode VecRestoreArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
335 PETSC_EXTERN PetscErrorCode VecGetArray1d(Vec,PetscInt,PetscInt,PetscScalar*[]);
336 PETSC_EXTERN PetscErrorCode VecRestoreArray1d(Vec,PetscInt,PetscInt,PetscScalar*[]);
337 
338 PETSC_EXTERN PetscErrorCode VecGetArray4dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
339 PETSC_EXTERN PetscErrorCode VecGetArray4dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
340 PETSC_EXTERN PetscErrorCode VecRestoreArray4dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
341 PETSC_EXTERN PetscErrorCode VecGetArray3dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
342 PETSC_EXTERN PetscErrorCode VecRestoreArray3dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
343 PETSC_EXTERN PetscErrorCode VecGetArray2dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
344 PETSC_EXTERN PetscErrorCode VecRestoreArray2dWrite(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
345 PETSC_EXTERN PetscErrorCode VecGetArray1dWrite(Vec,PetscInt,PetscInt,PetscScalar*[]);
346 PETSC_EXTERN PetscErrorCode VecRestoreArray1dWrite(Vec,PetscInt,PetscInt,PetscScalar*[]);
347 
348 PETSC_EXTERN PetscErrorCode VecGetArray4dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
349 PETSC_EXTERN PetscErrorCode VecRestoreArray4dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
350 PETSC_EXTERN PetscErrorCode VecGetArray3dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
351 PETSC_EXTERN PetscErrorCode VecRestoreArray3dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
352 PETSC_EXTERN PetscErrorCode VecGetArray2dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
353 PETSC_EXTERN PetscErrorCode VecRestoreArray2dRead(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
354 PETSC_EXTERN PetscErrorCode VecGetArray1dRead(Vec,PetscInt,PetscInt,PetscScalar*[]);
355 PETSC_EXTERN PetscErrorCode VecRestoreArray1dRead(Vec,PetscInt,PetscInt,PetscScalar*[]);
356 
357 PETSC_EXTERN PetscErrorCode VecPlaceArray(Vec,const PetscScalar[]);
358 PETSC_EXTERN PetscErrorCode VecResetArray(Vec);
359 PETSC_EXTERN PetscErrorCode VecReplaceArray(Vec,const PetscScalar[]);
360 
361 PETSC_EXTERN PetscErrorCode VecGetArrays(const Vec[],PetscInt,PetscScalar**[]);
362 PETSC_EXTERN PetscErrorCode VecRestoreArrays(const Vec[],PetscInt,PetscScalar**[]);
363 
364 PETSC_EXTERN PetscErrorCode VecView(Vec,PetscViewer);
365 PETSC_EXTERN PetscErrorCode VecEqual(Vec,Vec,PetscBool*);
366 PETSC_EXTERN PetscErrorCode VecLoad(Vec,PetscViewer);
367 
368 PETSC_EXTERN PetscErrorCode VecGetSize(Vec,PetscInt*);
369 PETSC_EXTERN PetscErrorCode VecGetLocalSize(Vec,PetscInt*);
370 PETSC_EXTERN PetscErrorCode VecGetOwnershipRange(Vec,PetscInt*,PetscInt*);
371 PETSC_EXTERN PetscErrorCode VecGetOwnershipRanges(Vec,const PetscInt*[]);
372 
373 PETSC_EXTERN PetscErrorCode VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
374 PETSC_EXTERN PetscErrorCode VecSetValuesLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
375 
376 PETSC_EXTERN PetscErrorCode VecCUDAGetArray(Vec,PetscScalar**);
377 PETSC_EXTERN PetscErrorCode VecCUDARestoreArray(Vec,PetscScalar**);
378 
379 PETSC_EXTERN PetscErrorCode VecCUDAGetArrayRead(Vec,const PetscScalar**);
380 PETSC_EXTERN PetscErrorCode VecCUDARestoreArrayRead(Vec,const PetscScalar**);
381 
382 PETSC_EXTERN PetscErrorCode VecCUDAGetArrayWrite(Vec,PetscScalar**);
383 PETSC_EXTERN PetscErrorCode VecCUDARestoreArrayWrite(Vec,PetscScalar**);
384 
385 PETSC_EXTERN PetscErrorCode VecCUDAPlaceArray(Vec,const PetscScalar[]);
386 PETSC_EXTERN PetscErrorCode VecCUDAReplaceArray(Vec,const PetscScalar[]);
387 PETSC_EXTERN PetscErrorCode VecCUDAResetArray(Vec);
388 
389 PETSC_EXTERN PetscErrorCode VecHIPGetArray(Vec,PetscScalar**);
390 PETSC_EXTERN PetscErrorCode VecHIPRestoreArray(Vec,PetscScalar**);
391 
392 PETSC_EXTERN PetscErrorCode VecHIPGetArrayRead(Vec,const PetscScalar**);
393 PETSC_EXTERN PetscErrorCode VecHIPRestoreArrayRead(Vec,const PetscScalar**);
394 
395 PETSC_EXTERN PetscErrorCode VecHIPGetArrayWrite(Vec,PetscScalar**);
396 PETSC_EXTERN PetscErrorCode VecHIPRestoreArrayWrite(Vec,PetscScalar**);
397 
398 PETSC_EXTERN PetscErrorCode VecHIPPlaceArray(Vec,const PetscScalar[]);
399 PETSC_EXTERN PetscErrorCode VecHIPReplaceArray(Vec,const PetscScalar[]);
400 PETSC_EXTERN PetscErrorCode VecHIPResetArray(Vec);
401 
402 PETSC_EXTERN PetscErrorCode VecViennaCLGetCLContext(Vec, PETSC_UINTPTR_T*);
403 PETSC_EXTERN PetscErrorCode VecViennaCLGetCLQueue(Vec, PETSC_UINTPTR_T*);
404 PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMemRead(Vec, PETSC_UINTPTR_T*);
405 PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMemWrite(Vec, PETSC_UINTPTR_T*);
406 PETSC_EXTERN PetscErrorCode VecViennaCLRestoreCLMemWrite(Vec);
407 PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMem(Vec, PETSC_UINTPTR_T*);
408 PETSC_EXTERN PetscErrorCode VecViennaCLRestoreCLMem(Vec);
409 
410 /*MC
411    VecSetValueLocal - Set a single entry into a vector using the local numbering
412 
413    Synopsis:
414    #include <petscvec.h>
415    PetscErrorCode VecSetValueLocal(Vec v,PetscInt row,PetscScalar value, InsertMode mode);
416 
417    Not Collective
418 
419    Input Parameters:
420 +  v - the vector
421 .  row - the row location of the entry
422 .  value - the value to insert
423 -  mode - either INSERT_VALUES or ADD_VALUES
424 
425    Notes:
426    For efficiency one should use VecSetValues() and set several or
427    many values simultaneously if possible.
428 
429    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
430    MUST be called after all calls to VecSetValues() have been completed.
431 
432    VecSetValues() uses 0-based indices in Fortran as well as in C.
433 
434    Level: beginner
435 
436 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
437 M*/
438 PETSC_STATIC_INLINE PetscErrorCode VecSetValueLocal(Vec v,PetscInt i,PetscScalar va,InsertMode mode) {return VecSetValuesLocal(v,1,&i,&va,mode);}
439 
440 PETSC_EXTERN PetscErrorCode VecSetValuesBlockedLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
441 PETSC_EXTERN PetscErrorCode VecGetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping*);
442 
443 PETSC_EXTERN PetscErrorCode VecDotBegin(Vec,Vec,PetscScalar *);
444 PETSC_EXTERN PetscErrorCode VecDotEnd(Vec,Vec,PetscScalar *);
445 PETSC_EXTERN PetscErrorCode VecTDotBegin(Vec,Vec,PetscScalar *);
446 PETSC_EXTERN PetscErrorCode VecTDotEnd(Vec,Vec,PetscScalar *);
447 PETSC_EXTERN PetscErrorCode VecNormBegin(Vec,NormType,PetscReal *);
448 PETSC_EXTERN PetscErrorCode VecNormEnd(Vec,NormType,PetscReal *);
449 
450 PETSC_EXTERN PetscErrorCode VecMDotBegin(Vec,PetscInt,const Vec[],PetscScalar[]);
451 PETSC_EXTERN PetscErrorCode VecMDotEnd(Vec,PetscInt,const Vec[],PetscScalar[]);
452 PETSC_EXTERN PetscErrorCode VecMTDotBegin(Vec,PetscInt,const Vec[],PetscScalar[]);
453 PETSC_EXTERN PetscErrorCode VecMTDotEnd(Vec,PetscInt,const Vec[],PetscScalar[]);
454 PETSC_EXTERN PetscErrorCode PetscCommSplitReductionBegin(MPI_Comm);
455 
456 PETSC_EXTERN PetscErrorCode VecBindToCPU(Vec,PetscBool);
457 PETSC_DEPRECATED_FUNCTION("Use VecBindToCPU (since v3.13)") PETSC_STATIC_INLINE PetscErrorCode VecPinToCPU(Vec v,PetscBool flg) {return VecBindToCPU(v,flg);}
458 PETSC_EXTERN PetscErrorCode VecSetPinnedMemoryMin(Vec,size_t);
459 PETSC_EXTERN PetscErrorCode VecGetPinnedMemoryMin(Vec,size_t *);
460 
461 /*E
462     PetscOffloadMask - indicates which memory (CPU, GPU, or none) contains valid data
463 
464    PETSC_OFFLOAD_UNALLOCATED  - no memory contains valid matrix entries; NEVER used for vectors
465    PETSC_OFFLOAD_GPU - GPU has valid vector/matrix entries
466    PETSC_OFFLOAD_CPU - CPU has valid vector/matrix entries
467    PETSC_OFFLOAD_BOTH - Both GPU and CPU have valid vector/matrix entries and they match
468    PETSC_OFFLOAD_VECKOKKOS - Reserved for Vec_Kokkos. The offload is managed by Kokkos, thus this flag is not used in Vec_Kokkos.
469 
470    Level: developer
471 E*/
472 typedef enum {PETSC_OFFLOAD_UNALLOCATED=0x0,PETSC_OFFLOAD_CPU=0x1,PETSC_OFFLOAD_GPU=0x2,PETSC_OFFLOAD_BOTH=0x3,PETSC_OFFLOAD_VECKOKKOS=0x100} PetscOffloadMask;
473 PETSC_EXTERN PetscErrorCode VecGetOffloadMask(Vec,PetscOffloadMask *);
474 
475 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_IGNORE_NEGATIVE_INDICES,VEC_SUBSET_OFF_PROC_ENTRIES} VecOption;
476 PETSC_EXTERN PetscErrorCode VecSetOption(Vec,VecOption,PetscBool);
477 
478 PETSC_EXTERN PetscErrorCode VecGetArray(Vec,PetscScalar**);
479 PETSC_EXTERN PetscErrorCode VecGetArrayWrite(Vec,PetscScalar**);
480 PETSC_EXTERN PetscErrorCode VecGetArrayRead(Vec,const PetscScalar**);
481 PETSC_EXTERN PetscErrorCode VecRestoreArray(Vec,PetscScalar**);
482 PETSC_EXTERN PetscErrorCode VecRestoreArrayWrite(Vec,PetscScalar**);
483 PETSC_EXTERN PetscErrorCode VecRestoreArrayRead(Vec,const PetscScalar**);
484 PETSC_EXTERN PetscErrorCode VecGetLocalVector(Vec,Vec);
485 PETSC_EXTERN PetscErrorCode VecRestoreLocalVector(Vec,Vec);
486 PETSC_EXTERN PetscErrorCode VecGetLocalVectorRead(Vec,Vec);
487 PETSC_EXTERN PetscErrorCode VecRestoreLocalVectorRead(Vec,Vec);
488 PETSC_EXTERN PetscErrorCode VecGetArrayAndMemType(Vec,PetscScalar**,PetscMemType*);
489 PETSC_EXTERN PetscErrorCode VecRestoreArrayAndMemType(Vec,PetscScalar**);
490 PETSC_EXTERN PetscErrorCode VecGetArrayReadAndMemType(Vec,const PetscScalar**,PetscMemType*);
491 PETSC_EXTERN PetscErrorCode VecRestoreArrayReadAndMemType(Vec,const PetscScalar**);
492 
493 /*@C
494    VecGetArrayPair - Accesses a pair of pointers for two vectors that may be common. When not common the first is read only
495 
496    Logically Collective on x
497 
498    Input Parameters:
499 +  x - the vector
500 -  y - the second vector
501 
502    Output Parameters:
503 +  xv - location to put pointer to the first array
504 -  yv - location to put pointer to the second array
505 
506    Level: developer
507 
508    Not available from Fortran
509 
510 .seealso: VecGetArray(), VecGetArrayRead(), VecRestoreArrayPair()
511 
512 @*/
513 PETSC_STATIC_INLINE PetscErrorCode VecGetArrayPair(Vec x,Vec y,PetscScalar **xv,PetscScalar **yv)
514 {
515   PetscErrorCode ierr;
516 
517   PetscFunctionBegin;
518   ierr = VecGetArray(y,yv);CHKERRQ(ierr);
519   if (x != y) {
520     ierr = VecGetArrayRead(x,(const PetscScalar **)xv);CHKERRQ(ierr);
521   } else {
522     *xv = *yv;
523   }
524   PetscFunctionReturn(0);
525 }
526 
527 /*@C
528    VecRestoreArrayPair - Returns a pair of pointers for two vectors that may be common. When not common the first is read only
529 
530    Logically Collective on x
531 
532    Input Parameters:
533 +  x - the vector
534 -  y - the second vector
535 
536    Output Parameters:
537 +  xv - location to put pointer to the first array
538 -  yv - location to put pointer to the second array
539 
540    Level: developer
541 
542    Not available from Fortran
543 
544 .seealso: VecGetArray(), VecGetArrayRead(), VecGetArrayPair()
545 
546 @*/
547 PETSC_STATIC_INLINE PetscErrorCode VecRestoreArrayPair(Vec x,Vec y,PetscScalar **xv,PetscScalar **yv)
548 {
549   PetscErrorCode ierr;
550 
551   PetscFunctionBegin;
552   ierr = VecRestoreArray(y,yv);CHKERRQ(ierr);
553   if (x != y) {
554     ierr = VecRestoreArrayRead(x,(const PetscScalar **)xv);CHKERRQ(ierr);
555   }
556   PetscFunctionReturn(0);
557 }
558 
559 #if defined(PETSC_USE_DEBUG)
560 PETSC_EXTERN PetscErrorCode VecLockReadPush(Vec);
561 PETSC_EXTERN PetscErrorCode VecLockReadPop(Vec);
562 /* We also have a non-public VecLockWriteSet_Private() in vecimpl.h */
563 PETSC_EXTERN PetscErrorCode VecLockGet(Vec,PetscInt*);
564 PETSC_STATIC_INLINE PetscErrorCode VecSetErrorIfLocked(Vec x,PetscInt arg)
565 {
566   PetscInt       state;
567   PetscErrorCode ierr;
568 
569   PetscFunctionBegin;
570   ierr = VecLockGet(x,&state);CHKERRQ(ierr);
571   if (state != 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE," Vec is already locked for read-only or read/write access, argument # %d",arg);
572   PetscFunctionReturn(0);
573 }
574 /* The three are deprecated */
575 PETSC_EXTERN PETSC_DEPRECATED_FUNCTION("Use VecLockReadPush() (since version 3.11)") PetscErrorCode VecLockPush(Vec);
576 PETSC_EXTERN PETSC_DEPRECATED_FUNCTION("Use VecLockReadPop() (since version 3.11)")  PetscErrorCode VecLockPop(Vec);
577 #define VecLocked(x,arg) VecSetErrorIfLocked(x,arg) PETSC_DEPRECATED_MACRO("GCC warning \"Use VecSetErrorIfLocked() (since version 3.11)\"")
578 #else
579 #define VecLockReadPush(x)           0
580 #define VecLockReadPop(x)            0
581 #define VecLockGet(x,s)              *(s) = 0
582 #define VecSetErrorIfLocked(x,arg)   0
583 /* The three are deprecated */
584 #define VecLockPush(x)               0
585 #define VecLockPop(x)                0
586 #define VecLocked(x,arg)             0
587 #endif
588 
589 PETSC_EXTERN PetscErrorCode VecValidValues(Vec,PetscInt,PetscBool);
590 
591 /*
592     These numbers need to match the entries in
593   the function table in vecimpl.h
594 */
595 typedef enum { VECOP_DUPLICATE = 0, VECOP_VIEW = 33, VECOP_LOAD = 41, VECOP_VIEWNATIVE = 68, VECOP_LOADNATIVE = 69 } VecOperation;
596 PETSC_EXTERN PetscErrorCode VecSetOperation(Vec,VecOperation,void(*)(void));
597 
598 /*
599      Routines for dealing with ghosted vectors:
600   vectors with ghost elements at the end of the array.
601 */
602 PETSC_EXTERN PetscErrorCode VecMPISetGhost(Vec,PetscInt,const PetscInt[]);
603 PETSC_EXTERN PetscErrorCode VecCreateGhost(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
604 PETSC_EXTERN PetscErrorCode VecCreateGhostWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
605 PETSC_EXTERN PetscErrorCode VecCreateGhostBlock(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
606 PETSC_EXTERN PetscErrorCode VecCreateGhostBlockWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
607 PETSC_EXTERN PetscErrorCode VecGhostGetLocalForm(Vec,Vec*);
608 PETSC_EXTERN PetscErrorCode VecGhostRestoreLocalForm(Vec,Vec*);
609 PETSC_EXTERN PetscErrorCode VecGhostIsLocalForm(Vec,Vec,PetscBool*);
610 PETSC_EXTERN PetscErrorCode VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
611 PETSC_EXTERN PetscErrorCode VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);
612 
613 PETSC_EXTERN PetscErrorCode VecConjugate(Vec);
614 PETSC_EXTERN PetscErrorCode VecImaginaryPart(Vec);
615 PETSC_EXTERN PetscErrorCode VecRealPart(Vec);
616 
617 PETSC_EXTERN PetscErrorCode VecScatterCreateToAll(Vec,VecScatter*,Vec*);
618 PETSC_EXTERN PetscErrorCode VecScatterCreateToZero(Vec,VecScatter*,Vec*);
619 
620 PETSC_EXTERN PetscErrorCode ISComplementVec(IS,Vec,IS*);
621 PETSC_EXTERN PetscErrorCode VecPow(Vec, PetscScalar);
622 PETSC_EXTERN PetscErrorCode VecMedian(Vec, Vec, Vec, Vec);
623 PETSC_EXTERN PetscErrorCode VecWhichInactive(Vec, Vec, Vec, Vec, PetscBool, IS *);
624 PETSC_EXTERN PetscErrorCode VecWhichBetween(Vec, Vec, Vec, IS *);
625 PETSC_EXTERN PetscErrorCode VecWhichBetweenOrEqual(Vec, Vec, Vec, IS *);
626 PETSC_EXTERN PetscErrorCode VecWhichGreaterThan(Vec, Vec, IS *);
627 PETSC_EXTERN PetscErrorCode VecWhichLessThan(Vec, Vec, IS *);
628 PETSC_EXTERN PetscErrorCode VecWhichEqual(Vec, Vec, IS *);
629 PETSC_EXTERN PetscErrorCode VecISAXPY(Vec, IS, PetscScalar,Vec);
630 PETSC_EXTERN PetscErrorCode VecISCopy(Vec, IS, ScatterMode, Vec);
631 PETSC_EXTERN PetscErrorCode VecISSet(Vec,IS, PetscScalar);
632 PETSC_EXTERN PetscErrorCode VecBoundGradientProjection(Vec, Vec, Vec, Vec, Vec);
633 PETSC_EXTERN PetscErrorCode VecStepBoundInfo(Vec,Vec,Vec,Vec,PetscReal*, PetscReal*,PetscReal*);
634 PETSC_EXTERN PetscErrorCode VecStepMax(Vec, Vec, PetscReal *);
635 PETSC_EXTERN PetscErrorCode VecStepMaxBounded(Vec,Vec,Vec,Vec,PetscReal*);
636 
637 PETSC_EXTERN PetscErrorCode PetscViewerMathematicaGetVector(PetscViewer, Vec);
638 PETSC_EXTERN PetscErrorCode PetscViewerMathematicaPutVector(PetscViewer, Vec);
639 
640 /*S
641      Vecs - Collection of vectors where the data for the vectors is stored in
642             one contiguous memory
643 
644    Level: advanced
645 
646    Notes:
647     Temporary construct for handling multiply right hand side solves
648 
649     This is faked by storing a single vector that has enough array space for
650     n vectors
651 
652 S*/
653         struct _n_Vecs  {PetscInt n; Vec v;};
654 typedef struct _n_Vecs* Vecs;
655 PETSC_EXTERN PetscErrorCode VecsDestroy(Vecs);
656 PETSC_EXTERN PetscErrorCode VecsCreateSeq(MPI_Comm,PetscInt,PetscInt,Vecs*);
657 PETSC_EXTERN PetscErrorCode VecsCreateSeqWithArray(MPI_Comm,PetscInt,PetscInt,PetscScalar*,Vecs*);
658 PETSC_EXTERN PetscErrorCode VecsDuplicate(Vecs,Vecs*);
659 
660 #if defined(PETSC_HAVE_VIENNACL)
661 typedef struct _p_PetscViennaCLIndices* PetscViennaCLIndices;
662 PETSC_EXTERN PetscErrorCode PetscViennaCLIndicesCreate(PetscInt, PetscInt*,PetscInt, PetscInt*,PetscViennaCLIndices*);
663 PETSC_EXTERN PetscErrorCode PetscViennaCLIndicesDestroy(PetscViennaCLIndices*);
664 PETSC_EXTERN PetscErrorCode VecViennaCLCopyToGPUSome_Public(Vec,PetscViennaCLIndices);
665 PETSC_EXTERN PetscErrorCode VecViennaCLCopyFromGPUSome_Public(Vec,PetscViennaCLIndices);
666 PETSC_EXTERN PetscErrorCode VecCreateSeqViennaCL(MPI_Comm,PetscInt,Vec*);
667 PETSC_EXTERN PetscErrorCode VecCreateMPIViennaCL(MPI_Comm,PetscInt,PetscInt,Vec*);
668 #endif
669 #if defined(PETSC_HAVE_CUDA) || defined(PETSC_HAVE_HIP)
670 PETSC_EXTERN PetscErrorCode VecScatterInitializeForGPU(VecScatter,Vec);
671 PETSC_EXTERN PetscErrorCode VecScatterFinalizeForGPU(VecScatter);
672 #endif
673 #if defined(PETSC_HAVE_CUDA)
674 PETSC_EXTERN PetscErrorCode VecCreateSeqCUDA(MPI_Comm,PetscInt,Vec*);
675 PETSC_EXTERN PetscErrorCode VecCreateSeqCUDAWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar*,Vec*);
676 PETSC_EXTERN PetscErrorCode VecCreateSeqCUDAWithArrays(MPI_Comm,PetscInt,PetscInt,const PetscScalar*,const PetscScalar*,Vec*);
677 PETSC_EXTERN PetscErrorCode VecCreateMPICUDA(MPI_Comm,PetscInt,PetscInt,Vec*);
678 PETSC_EXTERN PetscErrorCode VecCreateMPICUDAWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar*,Vec*);
679 PETSC_EXTERN PetscErrorCode VecCreateMPICUDAWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar*,const PetscScalar*,Vec*);
680 #endif
681 #if defined(PETSC_HAVE_HIP)
682 PETSC_EXTERN PetscErrorCode VecCreateSeqHIP(MPI_Comm,PetscInt,Vec*);
683 PETSC_EXTERN PetscErrorCode VecCreateSeqHIPWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar*,Vec*);
684 PETSC_EXTERN PetscErrorCode VecCreateSeqHIPWithArrays(MPI_Comm,PetscInt,PetscInt,const PetscScalar*,const PetscScalar*,Vec*);
685 PETSC_EXTERN PetscErrorCode VecCreateMPIHIP(MPI_Comm,PetscInt,PetscInt,Vec*);
686 PETSC_EXTERN PetscErrorCode VecCreateMPIHIPWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar*,Vec*);
687 PETSC_EXTERN PetscErrorCode VecCreateMPIHIPWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar*,const PetscScalar*,Vec*);
688 #endif
689 #if defined(PETSC_HAVE_KOKKOS_KERNELS)
690 PETSC_EXTERN PetscErrorCode VecCreateSeqKokkos(MPI_Comm,PetscInt,Vec*);
691 PETSC_EXTERN PetscErrorCode VecCreateSeqKokkosWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar*,Vec*);
692 PETSC_EXTERN PetscErrorCode VecCreateMPIKokkos(MPI_Comm,PetscInt,PetscInt,Vec*);
693 PETSC_EXTERN PetscErrorCode VecCreateMPIKokkosWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscScalar*,Vec*);
694 #endif
695 
696 PETSC_EXTERN PetscErrorCode VecNestGetSubVecs(Vec,PetscInt*,Vec**);
697 PETSC_EXTERN PetscErrorCode VecNestGetSubVec(Vec,PetscInt,Vec*);
698 PETSC_EXTERN PetscErrorCode VecNestSetSubVecs(Vec,PetscInt,PetscInt*,Vec*);
699 PETSC_EXTERN PetscErrorCode VecNestSetSubVec(Vec,PetscInt,Vec);
700 PETSC_EXTERN PetscErrorCode VecCreateNest(MPI_Comm,PetscInt,IS*,Vec*,Vec*);
701 PETSC_EXTERN PetscErrorCode VecNestGetSize(Vec,PetscInt*);
702 
703 PETSC_EXTERN PetscErrorCode PetscOptionsGetVec(PetscOptions,const char[],const char[],Vec,PetscBool*);
704 PETSC_EXTERN PetscErrorCode VecChop(Vec,PetscReal);
705 
706 PETSC_EXTERN PetscErrorCode VecGetLayout(Vec,PetscLayout*);
707 PETSC_EXTERN PetscErrorCode VecSetLayout(Vec,PetscLayout);
708 
709 PETSC_EXTERN PetscErrorCode PetscSectionVecView(PetscSection, Vec, PetscViewer);
710 PETSC_EXTERN PetscErrorCode VecGetValuesSection(Vec, PetscSection, PetscInt, PetscScalar **);
711 PETSC_EXTERN PetscErrorCode VecSetValuesSection(Vec, PetscSection, PetscInt, PetscScalar [], InsertMode);
712 PETSC_EXTERN PetscErrorCode PetscSectionVecNorm(PetscSection, PetscSection, Vec, NormType, PetscReal []);
713 
714 /*S
715   VecTagger - Object used to manage the tagging of a subset of indices based on the values of a vector.  The
716               motivating application is the selection of cells for refinement or coarsening based on vector containing
717               the values in an error indicator metric.
718 
719   Level: advanced
720 S*/
721 typedef struct _p_VecTagger *VecTagger;
722 
723 /*J
724   VecTaggerType - String with the name of a VecTagger type
725 
726   Level: advanced
727 J*/
728 typedef const char* VecTaggerType;
729 /* tag where the vector values are in a box of explicitly defined values */
730 #define VECTAGGERABSOLUTE   "absolute"
731 /* tag where the vector values are in a box of values relative to the set of all values in the vector */
732 #define VECTAGGERRELATIVE   "relative"
733 /* tag where the vector values are in a relative range of the *cumulative distribution* of values in the vector */
734 #define VECTAGGERCDF        "cdf"
735 /* tag a vector as the union of other tags */
736 #define VECTAGGEROR         "or"
737 /* tag a vector as the intersection of other tags */
738 #define VECTAGGERAND        "and"
739 
740 PETSC_EXTERN PetscClassId VEC_TAGGER_CLASSID;
741 PETSC_EXTERN PetscFunctionList VecTaggerList;
742 PETSC_EXTERN PetscErrorCode VecTaggerRegister(const char[],PetscErrorCode (*) (VecTagger));
743 
744 PETSC_EXTERN PetscErrorCode VecTaggerCreate(MPI_Comm,VecTagger *);
745 PETSC_EXTERN PetscErrorCode VecTaggerSetBlockSize(VecTagger,PetscInt);
746 PETSC_EXTERN PetscErrorCode VecTaggerGetBlockSize(VecTagger,PetscInt*);
747 PETSC_EXTERN PetscErrorCode VecTaggerSetType(VecTagger,VecTaggerType);
748 PETSC_EXTERN PetscErrorCode VecTaggerGetType(VecTagger,VecTaggerType *);
749 PETSC_EXTERN PetscErrorCode VecTaggerSetInvert(VecTagger,PetscBool);
750 PETSC_EXTERN PetscErrorCode VecTaggerGetInvert(VecTagger,PetscBool*);
751 PETSC_EXTERN PetscErrorCode VecTaggerSetFromOptions(VecTagger);
752 PETSC_EXTERN PetscErrorCode VecTaggerSetUp(VecTagger);
753 PETSC_EXTERN PetscErrorCode VecTaggerView(VecTagger,PetscViewer);
754 PETSC_EXTERN PetscErrorCode VecTaggerComputeIS(VecTagger,Vec,IS *);
755 PETSC_EXTERN PetscErrorCode VecTaggerDestroy(VecTagger *);
756 
757 /*S
758    VecTaggerBox - A box range used to tag values.  For real scalars, this is just a closed interval; for complex scalars, the box is the closed region in the complex plane
759    such that real(min) <= real(z) <= real(max) and imag(min) <= imag(z) <= imag(max).  INF is an acceptable endpoint.
760 
761    Level: beginner
762 
763 .seealso: VecTaggerComputeIntervals()
764 S*/
765 typedef struct {
766   PetscScalar min;
767   PetscScalar max;
768 } VecTaggerBox;
769 PETSC_EXTERN PetscErrorCode VecTaggerComputeBoxes(VecTagger,Vec,PetscInt *,VecTaggerBox **);
770 
771 PETSC_EXTERN PetscErrorCode VecTaggerAbsoluteSetBox(VecTagger,VecTaggerBox *);
772 PETSC_EXTERN PetscErrorCode VecTaggerAbsoluteGetBox(VecTagger,const VecTaggerBox **);
773 
774 PETSC_EXTERN PetscErrorCode VecTaggerRelativeSetBox(VecTagger,VecTaggerBox *);
775 PETSC_EXTERN PetscErrorCode VecTaggerRelativeGetBox(VecTagger,const VecTaggerBox **);
776 
777 PETSC_EXTERN PetscErrorCode VecTaggerCDFSetBox(VecTagger,VecTaggerBox *);
778 PETSC_EXTERN PetscErrorCode VecTaggerCDFGetBox(VecTagger,const VecTaggerBox **);
779 
780 /*E
781   VecTaggerCDFMethod - Determines what method is used to compute absolute values from cumulative distribution values (e.g., what value is the preimage of .95 in the cdf).  Relevant only in parallel: in serial it is directly computed.
782 
783   Level: advanced
784 .seealso: VecTaggerCDFSetMethod(), VecTaggerCDFMethods
785 E*/
786 typedef enum {VECTAGGER_CDF_GATHER,VECTAGGER_CDF_ITERATIVE,VECTAGGER_CDF_NUM_METHODS} VecTaggerCDFMethod;
787 PETSC_EXTERN const char *const VecTaggerCDFMethods[];
788 
789 PETSC_EXTERN PetscErrorCode VecTaggerCDFSetMethod(VecTagger,VecTaggerCDFMethod);
790 PETSC_EXTERN PetscErrorCode VecTaggerCDFGetMethod(VecTagger,VecTaggerCDFMethod*);
791 PETSC_EXTERN PetscErrorCode VecTaggerCDFIterativeSetTolerances(VecTagger,PetscInt,PetscReal,PetscReal);
792 PETSC_EXTERN PetscErrorCode VecTaggerCDFIterativeGetTolerances(VecTagger,PetscInt*,PetscReal*,PetscReal*);
793 
794 PETSC_EXTERN PetscErrorCode VecTaggerOrSetSubs(VecTagger,PetscInt,VecTagger*,PetscCopyMode);
795 PETSC_EXTERN PetscErrorCode VecTaggerOrGetSubs(VecTagger,PetscInt*,VecTagger**);
796 
797 PETSC_EXTERN PetscErrorCode VecTaggerAndSetSubs(VecTagger,PetscInt,VecTagger*,PetscCopyMode);
798 PETSC_EXTERN PetscErrorCode VecTaggerAndGetSubs(VecTagger,PetscInt*,VecTagger**);
799 
800 PETSC_EXTERN PetscErrorCode VecTaggerInitializePackage(void);
801 PETSC_EXTERN PetscErrorCode VecTaggerFinalizePackage(void);
802 
803 #endif
804