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