xref: /petsc/include/petscvec.h (revision 06262987a8ce5e8f5ab66e2c6a1b86bf95f4bf83) 
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 
118 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecInitializePackage(char *);
119 
120 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreate(MPI_Comm,Vec*);
121 PetscPolymorphicSubroutine(VecCreate,(Vec *x),(PETSC_COMM_SELF,x))
122 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateSeq(MPI_Comm,PetscInt,Vec*);
123 PetscPolymorphicSubroutine(VecCreateSeq,(PetscInt n,Vec *x),(PETSC_COMM_SELF,n,x))
124 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateMPI(MPI_Comm,PetscInt,PetscInt,Vec*);
125 PetscPolymorphicSubroutine(VecCreateMPI,(PetscInt n,PetscInt N,Vec *x),(PETSC_COMM_WORLD,n,N,x))
126 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateSeqWithArray(MPI_Comm,PetscInt,const PetscScalar[],Vec*);
127 PetscPolymorphicSubroutine(VecCreateSeqWithArray,(PetscInt n,PetscScalar s[],Vec *x),(PETSC_COMM_SELF,n,s,x))
128 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateMPIWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar[],Vec*);
129 PetscPolymorphicSubroutine(VecCreateMPIWithArray,(PetscInt n,PetscInt N,PetscScalar s[],Vec *x),(PETSC_COMM_WORLD,n,N,s,x))
130 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateShared(MPI_Comm,PetscInt,PetscInt,Vec*);
131 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetFromOptions(Vec);
132 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPrintHelp(Vec);
133 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetUp(Vec);
134 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDestroy(Vec);
135 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecZeroEntries(Vec);
136 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOptionsPrefix(Vec,const char[]);
137 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAppendOptionsPrefix(Vec,const char[]);
138 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetOptionsPrefix(Vec,const char*[]);
139 
140 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetSizes(Vec,PetscInt,PetscInt);
141 
142 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDot(Vec,Vec,PetscScalar*);
143 PetscPolymorphicFunction(VecDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
144 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDot(Vec,Vec,PetscScalar*);
145 PetscPolymorphicFunction(VecTDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
146 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMDot(Vec,PetscInt,const Vec[],PetscScalar*);
147 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMTDot(Vec,PetscInt,const Vec[],PetscScalar*);
148 
149 /*E
150     NormType - determines what type of norm to compute
151 
152     Level: beginner
153 
154 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
155 E*/
156 typedef enum {NORM_1=0,NORM_2=1,NORM_FROBENIUS=2,NORM_INFINITY=3,NORM_1_AND_2=4} NormType;
157 extern const char *NormTypes[];
158 #define NORM_MAX NORM_INFINITY
159 
160 /*MC
161      NORM_1 - the one norm, ||v|| = sum_i | v_i |. ||A|| = max_j || v_*j ||, maximum column sum
162 
163    Level: beginner
164 
165 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_2, NORM_FROBENIUS,
166            NORM_INFINITY, NORM_1_AND_2
167 
168 M*/
169 
170 /*MC
171      NORM_2 - the two norm, ||v|| = sqrt(sum_i (v_i)^2) (vectors only)
172 
173    Level: beginner
174 
175 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_FROBENIUS,
176            NORM_INFINITY, NORM_1_AND_2
177 
178 M*/
179 
180 /*MC
181      NORM_FROBENIUS - ||A|| = sqrt(sum_ij (A_ij)^2), same as NORM_2 for vectors
182 
183    Level: beginner
184 
185 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
186            NORM_INFINITY, NORM_1_AND_2
187 
188 M*/
189 
190 /*MC
191      NORM_INFINITY - ||v|| = max_i |v_i|. ||A|| = max_i || v_i* ||, maximum row sum
192 
193    Level: beginner
194 
195 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
196            NORM_FROBINIUS, NORM_1_AND_2
197 
198 M*/
199 
200 /*MC
201      NORM_1_AND_2 - computes both the 1 and 2 norm of a vector
202 
203    Level: beginner
204 
205 .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2,
206            NORM_FROBINIUS, NORM_INFINITY
207 
208 M*/
209 
210 /*MC
211      NORM_MAX - see NORM_INFINITY
212 
213    Level: beginner
214 
215 M*/
216 
217 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNorm(Vec,NormType,PetscReal *);
218 PetscPolymorphicSubroutine(VecNorm,(Vec x,PetscReal *r),(x,NORM_2,r))
219 PetscPolymorphicFunction(VecNorm,(Vec x,NormType t),(x,t,&r),PetscReal,r)
220 PetscPolymorphicFunction(VecNorm,(Vec x),(x,NORM_2,&r),PetscReal,r)
221 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormalize(Vec,PetscReal *);
222 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSum(Vec,PetscScalar*);
223 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMax(Vec,PetscInt*,PetscReal *);
224 PetscPolymorphicSubroutine(VecMax,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
225 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMin(Vec,PetscInt*,PetscReal *);
226 PetscPolymorphicSubroutine(VecMin,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
227 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScale(Vec v,PetscScalar a);
228 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec,Vec);
229 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec,PetscRandom);
230 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSet(Vec,PetscScalar);
231 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec,Vec);
232 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPY(Vec,PetscScalar,Vec);
233 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPBY(Vec,PetscScalar,PetscScalar,Vec);
234 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMAXPY(Vec,PetscInt,const PetscScalar[],Vec*);
235 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAYPX(Vec,PetscScalar,Vec);
236 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecWAXPY(Vec,PetscScalar,Vec,Vec);
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(Vec,PetscScalar);
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 PetscPolymorphicScalar(VecStrideScale,(Vec x,PetscInt i,PetscScalar _t),(x,i,&_T))
272 
273 
274 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGather(Vec,PetscInt,Vec,InsertMode);
275 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatter(Vec,PetscInt,Vec,InsertMode);
276 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGatherAll(Vec,Vec*,InsertMode);
277 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatterAll(Vec*,Vec,InsertMode);
278 
279 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValues(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
280 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetValues(Vec,PetscInt,const PetscInt[],PetscScalar[]);
281 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec);
282 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec);
283 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec,PetscInt,PetscInt);
284 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec,PetscViewer);
285 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
286 
287 extern PETSCVEC_DLLEXPORT PetscInt    VecSetValue_Row;
288 extern PETSCVEC_DLLEXPORT PetscScalar VecSetValue_Value;
289 /*MC
290    VecSetValue - Set a single entry into a vector.
291 
292    Synopsis:
293    PetscErrorCode VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode);
294 
295    Not Collective
296 
297    Input Parameters:
298 +  v - the vector
299 .  row - the row location of the entry
300 .  value - the value to insert
301 -  mode - either INSERT_VALUES or ADD_VALUES
302 
303    Notes:
304    For efficiency one should use VecSetValues() and set several or
305    many values simultaneously if possible.
306 
307    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
308    MUST be called after all calls to VecSetValues() have been completed.
309 
310    VecSetValues() uses 0-based indices in Fortran as well as in C.
311 
312    Level: beginner
313 
314 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
315 M*/
316 PETSC_STATIC_INLINE PetscErrorCode VecSetValue(Vec v,PetscInt i,PetscScalar va,InsertMode mode) {return VecSetValues(v,1,&i,&va,mode);}
317 
318 /*MC
319    VecSetValueLocal - Set a single entry into a vector using the local numbering
320 
321    Synopsis:
322    PetscErrorCode VecSetValueLocal(Vec v,int row,PetscScalar value, InsertMode mode);
323 
324    Not Collective
325 
326    Input Parameters:
327 +  v - the vector
328 .  row - the row location of the entry
329 .  value - the value to insert
330 -  mode - either INSERT_VALUES or ADD_VALUES
331 
332    Notes:
333    For efficiency one should use VecSetValues() and set several or
334    many values simultaneously if possible.
335 
336    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
337    MUST be called after all calls to VecSetValues() have been completed.
338 
339    VecSetValues() uses 0-based indices in Fortran as well as in C.
340 
341    Level: beginner
342 
343 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
344 M*/
345 #define VecSetValueLocal(v,i,va,mode) ((VecSetValue_Row = i,VecSetValue_Value = va,0) || VecSetValuesLocal(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))
346 
347 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetBlockSize(Vec,PetscInt);
348 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec,PetscInt*);
349 PetscPolymorphicFunction(VecGetBlockSize,(Vec x),(x,&i),PetscInt,i)
350 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlocked(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
351 
352 /* Dynamic creation and loading functions */
353 extern PetscFList VecList;
354 extern PetscTruth VecRegisterAllCalled;
355 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetType(Vec, VecType);
356 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetType(Vec, VecType *);
357 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegister(const char[],const char[],const char[],PetscErrorCode (*)(Vec));
358 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterAll(const char []);
359 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterDestroy(void);
360 
361 /*MC
362   VecRegisterDynamic - Adds a new vector component implementation
363 
364   Synopsis:
365   PetscErrorCode VecRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(Vec))
366 
367   Not Collective
368 
369   Input Parameters:
370 + name        - The name of a new user-defined creation routine
371 . path        - The path (either absolute or relative) of the library containing this routine
372 . func_name   - The name of routine to create method context
373 - create_func - The creation routine itself
374 
375   Notes:
376   VecRegisterDynamic() may be called multiple times to add several user-defined vectors
377 
378   If dynamic libraries are used, then the fourth input argument (routine_create) is ignored.
379 
380   Sample usage:
381 .vb
382     VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate);
383 .ve
384 
385   Then, your vector type can be chosen with the procedural interface via
386 .vb
387     VecCreate(MPI_Comm, Vec *);
388     VecSetType(Vec,"my_vector_name");
389 .ve
390    or at runtime via the option
391 .vb
392     -vec_type my_vector_name
393 .ve
394 
395   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
396          If your function is not being put into a shared library then use VecRegister() instead
397 
398   Level: advanced
399 
400 .keywords: Vec, register
401 .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister()
402 M*/
403 #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
404 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
405 #else
406 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
407 #endif
408 
409 
410 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
411 PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is1,Vec y,IS is2),(x,is1,y,is2,&s),VecScatter,s)
412 PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,IS is,Vec y,VecScatter *s),(x,is,y,PETSC_NULL,s))
413 PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is,Vec y),(x,is,y,PETSC_NULL,&s),VecScatter,s)
414 PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,Vec y,IS is,VecScatter *s),(x,PETSC_NULL,y,is,s))
415 PetscPolymorphicFunction(VecScatterCreate,(Vec x,Vec y,IS is),(x,PETSC_NULL,y,is,&s),VecScatter,s)
416 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
417 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
418 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
419 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterDestroy(VecScatter);
420 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCopy(VecScatter,VecScatter *);
421 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterView(VecScatter,PetscViewer);
422 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterRemap(VecScatter,PetscInt *,PetscInt*);
423 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterGetMerged(VecScatter,PetscTruth*);
424 
425 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray_Private(Vec,PetscScalar*[]);
426 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray_Private(Vec,PetscScalar*[]);
427 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
428 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
429 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
430 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
431 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
432 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
433 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
434 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
435 
436 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPlaceArray(Vec,const PetscScalar[]);
437 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec);
438 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecReplaceArray(Vec,const PetscScalar[]);
439 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArrays(const Vec[],PetscInt,PetscScalar**[]);
440 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArrays(const Vec[],PetscInt,PetscScalar**[]);
441 
442 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecValid(Vec,PetscTruth*);
443 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec,PetscViewer);
444 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec, char *);
445 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecEqual(Vec,Vec,PetscTruth*);
446 PetscPolymorphicFunction(VecEqual,(Vec x,Vec y),(x,y,&s),PetscTruth,s)
447 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoad(PetscViewer,VecType,Vec*);
448 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer,Vec);
449 
450 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec,PetscInt*);
451 PetscPolymorphicFunction(VecGetSize,(Vec x),(x,&s),PetscInt,s)
452 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec,PetscInt*);
453 PetscPolymorphicFunction(VecGetLocalSize,(Vec x),(x,&s),PetscInt,s)
454 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec,PetscInt*,PetscInt*);
455 
456 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
457 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
458 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
459 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlockedLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
460 
461 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotBegin(Vec,Vec,PetscScalar *);
462 PetscPolymorphicSubroutine(VecDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
463 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotEnd(Vec,Vec,PetscScalar *);
464 PetscPolymorphicFunction(VecDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
465 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotBegin(Vec,Vec,PetscScalar *);
466 PetscPolymorphicSubroutine(VecTDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
467 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotEnd(Vec,Vec,PetscScalar *);
468 PetscPolymorphicFunction(VecTDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
469 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormBegin(Vec,NormType,PetscReal *);
470 PetscPolymorphicSubroutine(VecNormBegin,(Vec x,NormType t),(x,t,PETSC_NULL))
471 PetscPolymorphicSubroutine(VecNormBegin,(Vec x),(x,NORM_2,PETSC_NULL))
472 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormEnd(Vec,NormType,PetscReal *);
473 PetscPolymorphicFunction(VecNormEnd,(Vec x,NormType t),(x,t,&s),PetscReal,s)
474 PetscPolymorphicFunction(VecNormEnd,(Vec x),(x,NORM_2,&s),PetscReal,s)
475 
476 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMDotBegin(Vec,PetscInt,const Vec[],PetscScalar *);
477 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMDotEnd(Vec,PetscInt,const Vec[],PetscScalar *);
478 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMTDotBegin(Vec,PetscInt,const Vec[],PetscScalar *);
479 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMTDotEnd(Vec,PetscInt,const Vec[],PetscScalar *);
480 
481 
482 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption;
483 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec,VecOption);
484 
485 /*
486    Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function
487    call overhead on any 'native' Vecs.
488 */
489 
490 PETSC_EXTERN_CXX_END
491 #include "private/vecimpl.h"
492 PETSC_EXTERN_CXX_BEGIN
493 
494 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecContourScale(Vec,PetscReal,PetscReal);
495 
496 /*
497     These numbers need to match the entries in
498   the function table in vecimpl.h
499 */
500 typedef enum { VECOP_VIEW = 32, VECOP_LOADINTOVECTOR = 38} VecOperation;
501 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec,VecOperation,void(*)(void));
502 
503 /*
504      Routines for dealing with ghosted vectors:
505   vectors with ghost elements at the end of the array.
506 */
507 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhost(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
508 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
509 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlock(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
510 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlockWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
511 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostGetLocalForm(Vec,Vec*);
512 PetscPolymorphicFunction(VecGhostGetLocalForm,(Vec x),(x,&s),Vec,s)
513 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostRestoreLocalForm(Vec,Vec*);
514 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
515 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);
516 
517 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec);
518 
519 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToAll(Vec,VecScatter*,Vec*);
520 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToZero(Vec,VecScatter*,Vec*);
521 
522 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaGetVector(PetscViewer, Vec);
523 EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaPutVector(PetscViewer, Vec);
524 
525 /*S
526      Vecs - Collection of vectors where the data for the vectors is stored in
527             one continquous memory
528 
529    Level: advanced
530 
531    Notes:
532     Temporary construct for handling multiply right hand side solves
533 
534     This is faked by storing a single vector that has enough array space for
535     n vectors
536 
537   Concepts: parallel decomposition
538 
539 S*/
540         struct _n_Vecs  {PetscInt n; Vec v;};
541 typedef struct _n_Vecs* Vecs;
542 #define VecsDestroy(x)            (VecDestroy((x)->v)         || PetscFree(x))
543 #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
544 #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
545 #define VecsDuplicate(x,y)        (PetscNew(struct _n_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))
546 
547 
548 PETSC_EXTERN_CXX_END
549 #endif
550