xref: /petsc/include/petscvec.h (revision 919b68f78566a3267d08cc498629dff2b42ebf53) 
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 #ifndef __PETSCVEC_H
8 #define __PETSCVEC_H
9 #include "petscis.h"
10 #include "petscsys.h"
11 PETSC_EXTERN_CXX_BEGIN
12 
13 /*S
14      PetscMap - Abstract PETSc object that defines the layout of vector and
15   matrices across processors
16 
17    Level: advanced
18 
19    Notes:
20     Does not play a role in the PETSc design, can be ignored
21 
22   Concepts: parallel decomposition
23 
24 .seealso:  PetscMapCreateMPI()
25 S*/
26 typedef struct _p_PetscMap*         PetscMap;
27 
28 #define MAP_SEQ "seq"
29 #define MAP_MPI "mpi"
30 #define PetscMapType const char*
31 
32 /* Logging support */
33 extern PetscCookie MAP_COOKIE;
34 
35 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapCreate(MPI_Comm,PetscMap*);
36 PetscPolymorphicSubroutine(PetscMapCreate,(PetscMap*m),(m))
37 PetscPolymorphicFunction(PetscMapCreate,(void),(PETSC_COMM_SELF,&m),PetscMap,m)
38 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapCreateMPI(MPI_Comm,PetscInt,PetscInt,PetscMap*);
39 PetscPolymorphicFunction(PetscMapCreateMPI,(MPI_Comm comm,PetscInt l,PetscInt g),(comm,l,g,&m),PetscMap,m)
40 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetFromOptions(PetscMap);
41 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapPrintHelp(PetscMap);
42 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapDestroy(PetscMap);
43 
44 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetUp(PetscMap);
45 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapView(PetscMap,PetscViewer);
46 
47 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetOptionsPrefix(PetscMap,const char[]);
48 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapAppendOptionsPrefix(PetscMap,const char[]);
49 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetOptionsPrefix(PetscMap,const char*[]);
50 
51 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetLocalSize(PetscMap,PetscInt);
52 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetLocalSize(PetscMap,PetscInt *);
53 PetscPolymorphicFunction(PetscMapGetLocalSize,(PetscMap m),(m,&s),PetscInt,s)
54 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetSize(PetscMap,PetscInt);
55 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetSize(PetscMap,PetscInt *);
56 PetscPolymorphicFunction(PetscMapGetSize,(PetscMap m),(m,&s),PetscInt,s)
57 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetLocalRange(PetscMap,PetscInt *,PetscInt *);
58 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetGlobalRange(PetscMap,PetscInt *[]);
59 
60 /* Dynamic creation and loading functions */
61 extern PetscFList PetscMapList;
62 extern PetscTruth PetscMapRegisterAllCalled;
63 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetType(PetscMap, PetscMapType);
64 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapGetType(PetscMap, PetscMapType *);
65 PetscPolymorphicFunction(PetscMapGetType,(PetscMap m),(m,&t),PetscMapType,t)
66 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapRegister(const char[],const char[],const char[],PetscErrorCode (*)(PetscMap));
67 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapRegisterAll(const char []);
68 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapRegisterDestroy(void);
69 #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
70 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0)
71 #else
72 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d)
73 #endif
74 
75 /*S
76      Vec - Abstract PETSc vector object
77 
78    Level: beginner
79 
80   Concepts: field variables, unknowns, arrays
81 
82 .seealso:  VecCreate(), VecType, VecSetType()
83 S*/
84 typedef struct _p_Vec*         Vec;
85 
86 /*S
87      VecScatter - Object used to manage communication of data
88        between vectors in parallel. Manages both scatters and gathers
89 
90    Level: beginner
91 
92   Concepts: scatter
93 
94 .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
95 S*/
96 typedef struct _p_VecScatter*  VecScatter;
97 
98 /*E
99     VecType - String with the name of a PETSc vector or the creation function
100        with an optional dynamic library name, for example
101        http://www.mcs.anl.gov/petsc/lib.a:myveccreate()
102 
103    Level: beginner
104 
105 .seealso: VecSetType(), Vec
106 E*/
107 #define VECSEQ         "seq"
108 #define VECMPI         "mpi"
109 #define VECFETI        "feti"
110 #define VECSHARED      "shared"
111 #define VecType const char*
112 
113 /* Logging support */
114 #define    VEC_FILE_COOKIE 1211214
115 extern PETSCVEC_DLLEXPORT PetscCookie VEC_COOKIE;
116 extern PETSCVEC_DLLEXPORT PetscCookie VEC_SCATTER_COOKIE;
117 extern PetscEvent    VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot;
118 extern PetscEvent    VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY;
119 extern PetscEvent    VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd;
120 extern PetscEvent    VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication;
121 extern PetscEvent    VEC_Swap, VEC_AssemblyBegin, VEC_NormBarrier;
122 
123 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecInitializePackage(char *);
124 
125 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreate(MPI_Comm,Vec*);
126 PetscPolymorphicSubroutine(VecCreate,(Vec *x),(PETSC_COMM_SELF,x))
127 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateSeq(MPI_Comm,PetscInt,Vec*);
128 PetscPolymorphicSubroutine(VecCreateSeq,(PetscInt n,Vec *x),(PETSC_COMM_SELF,n,x))
129 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateMPI(MPI_Comm,PetscInt,PetscInt,Vec*);
130 PetscPolymorphicSubroutine(VecCreateMPI,(PetscInt n,PetscInt N,Vec *x),(PETSC_COMM_WORLD,n,N,x))
131 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateSeqWithArray(MPI_Comm,PetscInt,const PetscScalar[],Vec*);
132 PetscPolymorphicSubroutine(VecCreateSeqWithArray,(PetscInt n,PetscScalar s[],Vec *x),(PETSC_COMM_SELF,n,s,x))
133 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateMPIWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar[],Vec*);
134 PetscPolymorphicSubroutine(VecCreateMPIWithArray,(PetscInt n,PetscInt N,PetscScalar s[],Vec *x),(PETSC_COMM_WORLD,n,N,s,x))
135 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateShared(MPI_Comm,PetscInt,PetscInt,Vec*);
136 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetFromOptions(Vec);
137 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPrintHelp(Vec);
138 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetUp(Vec);
139 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDestroy(Vec);
140 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecZeroEntries(Vec);
141 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOptionsPrefix(Vec,const char[]);
142 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAppendOptionsPrefix(Vec,const char[]);
143 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetOptionsPrefix(Vec,const char*[]);
144 
145 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetSizes(Vec,PetscInt,PetscInt);
146 
147 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDot(Vec,Vec,PetscScalar*);
148 PetscPolymorphicFunction(VecDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
149 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDot(Vec,Vec,PetscScalar*);
150 PetscPolymorphicFunction(VecTDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
151 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMDot(PetscInt,Vec,const Vec[],PetscScalar*);
152 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMTDot(PetscInt,Vec,const Vec[],PetscScalar*);
153 
154 /*E
155     NormType - determines what type of norm to compute
156 
157     Level: beginner
158 
159 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
160 E*/
161 typedef enum {NORM_1=0,NORM_2=1,NORM_FROBENIUS=2,NORM_INFINITY=3,NORM_1_AND_2=4} NormType;
162 extern const char *NormTypes[];
163 #define NORM_MAX NORM_INFINITY
164 
165 /*MC
166      NORM_1 - the one norm, ||v|| = sum_i | v_i |. ||A|| = max_j || v_*j ||, maximum column sum
167 
168    Level: beginner
169 
170 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_2, NORM_FROBENIUS,
171            NORM_INFINITY, NORM_1_AND_2
172 
173 M*/
174 
175 /*MC
176      NORM_2 - the two norm, ||v|| = sqrt(sum_i (v_i)^2) (vectors only)
177 
178    Level: beginner
179 
180 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_FROBENIUS,
181            NORM_INFINITY, NORM_1_AND_2
182 
183 M*/
184 
185 /*MC
186      NORM_FROBENIUS - ||A|| = sqrt(sum_ij (A_ij)^2), same as NORM_2 for vectors
187 
188    Level: beginner
189 
190 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
191            NORM_INFINITY, NORM_1_AND_2
192 
193 M*/
194 
195 /*MC
196      NORM_INFINITY - ||v|| = max_i |v_i|. ||A|| = max_i || v_i* ||, maximum row sum
197 
198    Level: beginner
199 
200 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
201            NORM_FROBINIUS, NORM_1_AND_2
202 
203 M*/
204 
205 /*MC
206      NORM_1_AND_2 - computes both the 1 and 2 norm of a vector
207 
208    Level: beginner
209 
210 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
211            NORM_FROBINIUS, NORM_INFINITY
212 
213 M*/
214 
215 /*MC
216      NORM_MAX - see NORM_INFINITY
217 
218    Level: beginner
219 
220 M*/
221 
222 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNorm(Vec,NormType,PetscReal *);
223 PetscPolymorphicSubroutine(VecNorm,(Vec x,PetscReal *r),(x,NORM_2,r))
224 PetscPolymorphicFunction(VecNorm,(Vec x,NormType t),(x,t,&r),PetscReal,r)
225 PetscPolymorphicFunction(VecNorm,(Vec x),(x,NORM_2,&r),PetscReal,r)
226 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormalize(Vec,PetscReal *);
227 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSum(Vec,PetscScalar*);
228 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMax(Vec,PetscInt*,PetscReal *);
229 PetscPolymorphicSubroutine(VecMax,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
230 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMin(Vec,PetscInt*,PetscReal *);
231 PetscPolymorphicSubroutine(VecMin,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
232 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScale(Vec v,PetscScalar a);
233 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec,Vec);
234 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec,PetscRandom);
235 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSet(Vec,PetscScalar);
236 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec,Vec);
237 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPY(Vec,PetscScalar,Vec);
238 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPBY(Vec,PetscScalar,PetscScalar,Vec);
239 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMAXPY(Vec,PetscInt,const PetscScalar[],Vec*);
240 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAYPX(Vec,PetscScalar,Vec);
241 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecWAXPY(Vec,PetscScalar,Vec,Vec);
242 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMax(Vec,Vec,Vec);
243 PetscPolymorphicSubroutine(VecPointwiseMax,(Vec x,Vec y),(x,y,y))
244 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMaxAbs(Vec,Vec,Vec);
245 PetscPolymorphicSubroutine(VecPointwiseMaxAbs,(Vec x,Vec y),(x,y,y))
246 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMin(Vec,Vec,Vec);
247 PetscPolymorphicSubroutine(VecPointwiseMin,(Vec x,Vec y),(x,y,y))
248 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMult(Vec,Vec,Vec);
249 PetscPolymorphicSubroutine(VecPointwiseMult,(Vec x,Vec y),(x,y,y))
250 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseDivide(Vec,Vec,Vec);
251 PetscPolymorphicSubroutine(VecPointwiseDivide,(Vec x,Vec y),(x,y,y))
252 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
253 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecShift(Vec,PetscScalar);
254 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecReciprocal(Vec);
255 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPermute(Vec, IS, PetscTruth);
256 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSqrt(Vec);
257 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAbs(Vec);
258 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicate(Vec,Vec*);
259 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicateVecs(Vec,PetscInt,Vec*[]);
260 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDestroyVecs(Vec[],PetscInt);
261 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetPetscMap(Vec,PetscMap*);
262 PetscPolymorphicFunction(VecGetPetscMap,(Vec x),(x,&y),PetscMap,y)
263 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideNormAll(Vec,NormType,PetscReal*);
264 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMaxAll(Vec,PetscInt *,PetscReal *);
265 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMinAll(Vec,PetscInt *,PetscReal *);
266 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScaleAll(Vec,PetscScalar*);
267 
268 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideNorm(Vec,PetscInt,NormType,PetscReal*);
269 PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i),(x,i,NORM_2,&r),PetscReal,r)
270 PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i,NormType t),(x,i,t,&r),PetscReal,r)
271 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMax(Vec,PetscInt,PetscInt *,PetscReal *);
272 PetscPolymorphicFunction(VecStrideMax,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
273 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMin(Vec,PetscInt,PetscInt *,PetscReal *);
274 PetscPolymorphicFunction(VecStrideMin,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
275 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScale(Vec,PetscInt,PetscScalar*);
276 PetscPolymorphicScalar(VecStrideScale,(Vec x,PetscInt i,PetscScalar _t),(x,i,&_T))
277 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGather(Vec,PetscInt,Vec,InsertMode);
278 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatter(Vec,PetscInt,Vec,InsertMode);
279 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGatherAll(Vec,Vec*,InsertMode);
280 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatterAll(Vec*,Vec,InsertMode);
281 
282 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValues(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
283 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetValues(Vec,PetscInt,const PetscInt[],PetscScalar[]);
284 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec);
285 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec);
286 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec,PetscInt,PetscInt);
287 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec,PetscViewer);
288 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
289 
290 extern PETSCVEC_DLLEXPORT PetscInt    VecSetValue_Row;
291 extern PETSCVEC_DLLEXPORT PetscScalar VecSetValue_Value;
292 /*MC
293    VecSetValue - Set a single entry into a vector.
294 
295    Synopsis:
296    PetscErrorCode VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode);
297 
298    Not Collective
299 
300    Input Parameters:
301 +  v - the vector
302 .  row - the row location of the entry
303 .  value - the value to insert
304 -  mode - either INSERT_VALUES or ADD_VALUES
305 
306    Notes:
307    For efficiency one should use VecSetValues() and set several or
308    many values simultaneously if possible.
309 
310    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
311    MUST be called after all calls to VecSetValues() have been completed.
312 
313    VecSetValues() uses 0-based indices in Fortran as well as in C.
314 
315    Level: beginner
316 
317 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
318 M*/
319 #define VecSetValue(v,i,va,mode) ((VecSetValue_Row = i,VecSetValue_Value = va,0) || VecSetValues(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))
320 
321 /*MC
322    VecSetValueLocal - Set a single entry into a vector using the local numbering
323 
324    Synopsis:
325    PetscErrorCode VecSetValueLocal(Vec v,int row,PetscScalar value, InsertMode mode);
326 
327    Not Collective
328 
329    Input Parameters:
330 +  v - the vector
331 .  row - the row location of the entry
332 .  value - the value to insert
333 -  mode - either INSERT_VALUES or ADD_VALUES
334 
335    Notes:
336    For efficiency one should use VecSetValues() and set several or
337    many values simultaneously if possible.
338 
339    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
340    MUST be called after all calls to VecSetValues() have been completed.
341 
342    VecSetValues() uses 0-based indices in Fortran as well as in C.
343 
344    Level: beginner
345 
346 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
347 M*/
348 #define VecSetValueLocal(v,i,va,mode) ((VecSetValue_Row = i,VecSetValue_Value = va,0) || VecSetValuesLocal(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))
349 
350 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetBlockSize(Vec,PetscInt);
351 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec,PetscInt*);
352 PetscPolymorphicFunction(VecGetBlockSize,(Vec x),(x,&i),PetscInt,i)
353 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlocked(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
354 
355 /* Dynamic creation and loading functions */
356 extern PetscFList VecList;
357 extern PetscTruth VecRegisterAllCalled;
358 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetType(Vec, VecType);
359 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetType(Vec, VecType *);
360 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegister(const char[],const char[],const char[],PetscErrorCode (*)(Vec));
361 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterAll(const char []);
362 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterDestroy(void);
363 
364 /*MC
365   VecRegisterDynamic - Adds a new vector component implementation
366 
367   Synopsis:
368   PetscErrorCode VecRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(Vec))
369 
370   Not Collective
371 
372   Input Parameters:
373 + name        - The name of a new user-defined creation routine
374 . path        - The path (either absolute or relative) of the library containing this routine
375 . func_name   - The name of routine to create method context
376 - create_func - The creation routine itself
377 
378   Notes:
379   VecRegisterDynamic() may be called multiple times to add several user-defined vectors
380 
381   If dynamic libraries are used, then the fourth input argument (routine_create) is ignored.
382 
383   Sample usage:
384 .vb
385     VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate);
386 .ve
387 
388   Then, your vector type can be chosen with the procedural interface via
389 .vb
390     VecCreate(MPI_Comm, Vec *);
391     VecSetType(Vec,"my_vector_name");
392 .ve
393    or at runtime via the option
394 .vb
395     -vec_type my_vector_name
396 .ve
397 
398   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
399          If your function is not being put into a shared library then use VecRegister() instead
400 
401   Level: advanced
402 
403 .keywords: Vec, register
404 .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister()
405 M*/
406 #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
407 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
408 #else
409 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
410 #endif
411 
412 
413 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
414 PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is1,Vec y,IS is2),(x,is1,y,is2,&s),VecScatter,s)
415 PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,IS is,Vec y,VecScatter *s),(x,is,y,PETSC_NULL,s))
416 PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is,Vec y),(x,is,y,PETSC_NULL,&s),VecScatter,s)
417 PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,Vec y,IS is,VecScatter *s),(x,PETSC_NULL,y,is,s))
418 PetscPolymorphicFunction(VecScatterCreate,(Vec x,Vec y,IS is),(x,PETSC_NULL,y,is,&s),VecScatter,s)
419 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
420 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
421 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
422 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterDestroy(VecScatter);
423 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCopy(VecScatter,VecScatter *);
424 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterView(VecScatter,PetscViewer);
425 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterRemap(VecScatter,PetscInt *,PetscInt*);
426 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterGetMerged(VecScatter,PetscTruth*);
427 
428 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray_Private(Vec,PetscScalar*[]);
429 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray_Private(Vec,PetscScalar*[]);
430 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
431 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
432 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
433 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
434 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
435 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
436 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
437 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
438 
439 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPlaceArray(Vec,const PetscScalar[]);
440 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec);
441 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecReplaceArray(Vec,const PetscScalar[]);
442 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArrays(const Vec[],PetscInt,PetscScalar**[]);
443 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArrays(const Vec[],PetscInt,PetscScalar**[]);
444 
445 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecValid(Vec,PetscTruth*);
446 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec,PetscViewer);
447 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec, char *);
448 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecEqual(Vec,Vec,PetscTruth*);
449 PetscPolymorphicFunction(VecEqual,(Vec x,Vec y),(x,y,&s),PetscTruth,s)
450 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoad(PetscViewer,VecType,Vec*);
451 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer,Vec);
452 
453 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec,PetscInt*);
454 PetscPolymorphicFunction(VecGetSize,(Vec x),(x,&s),PetscInt,s)
455 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec,PetscInt*);
456 PetscPolymorphicFunction(VecGetLocalSize,(Vec x),(x,&s),PetscInt,s)
457 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec,PetscInt*,PetscInt*);
458 
459 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
460 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
461 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
462 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlockedLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
463 
464 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotBegin(Vec,Vec,PetscScalar *);
465 PetscPolymorphicSubroutine(VecDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
466 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotEnd(Vec,Vec,PetscScalar *);
467 PetscPolymorphicFunction(VecDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
468 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotBegin(Vec,Vec,PetscScalar *);
469 PetscPolymorphicSubroutine(VecTDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
470 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotEnd(Vec,Vec,PetscScalar *);
471 PetscPolymorphicFunction(VecTDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
472 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormBegin(Vec,NormType,PetscReal *);
473 PetscPolymorphicSubroutine(VecNormBegin,(Vec x,NormType t),(x,t,PETSC_NULL))
474 PetscPolymorphicSubroutine(VecNormBegin,(Vec x),(x,NORM_2,PETSC_NULL))
475 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormEnd(Vec,NormType,PetscReal *);
476 PetscPolymorphicFunction(VecNormEnd,(Vec x,NormType t),(x,t,&s),PetscReal,s)
477 PetscPolymorphicFunction(VecNormEnd,(Vec x),(x,NORM_2,&s),PetscReal,s)
478 
479 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption;
480 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec,VecOption);
481 
482 /*
483    Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function
484    call overhead on any 'native' Vecs.
485 */
486 
487 PETSC_EXTERN_CXX_END
488 #include "private/vecimpl.h"
489 PETSC_EXTERN_CXX_BEGIN
490 
491 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecContourScale(Vec,PetscReal,PetscReal);
492 
493 /*
494     These numbers need to match the entries in
495   the function table in vecimpl.h
496 */
497 typedef enum { VECOP_VIEW = 32,
498                VECOP_LOADINTOVECTOR = 38
499              } VecOperation;
500 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec,VecOperation,void(*)(void));
501 
502 /*
503      Routines for dealing with ghosted vectors:
504   vectors with ghost elements at the end of the array.
505 */
506 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhost(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
507 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
508 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlock(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
509 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlockWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
510 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostGetLocalForm(Vec,Vec*);
511 PetscPolymorphicFunction(VecGhostGetLocalForm,(Vec x),(x,&s),Vec,s)
512 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostRestoreLocalForm(Vec,Vec*);
513 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
514 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);
515 
516 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec);
517 
518 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToAll(Vec,VecScatter*,Vec*);
519 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToZero(Vec,VecScatter*,Vec*);
520 
521 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaGetVector(PetscViewer, Vec);
522 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaPutVector(PetscViewer, Vec);
523 
524 /*S
525      Vecs - Collection of vectors where the data for the vectors is stored in
526             one continquous memory
527 
528    Level: advanced
529 
530    Notes:
531     Temporary construct for handling multiply right hand side solves
532 
533     This is faked by storing a single vector that has enough array space for
534     n vectors
535 
536   Concepts: parallel decomposition
537 
538 S*/
539         struct _n_Vecs  {PetscInt n; Vec v;};
540 typedef struct _n_Vecs* Vecs;
541 #define VecsDestroy(x)            (VecDestroy((x)->v)         || PetscFree(x))
542 #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
543 #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
544 #define VecsDuplicate(x,y)        (PetscNew(struct _n_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))
545 
546 
547 PETSC_EXTERN_CXX_END
548 #endif
549