Actual source code: petscvec.h

  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: */

  7: #ifndef __PETSCVEC_H 
 9:  #include petscis.h
 10:  #include petscsys.h

 13: /*S
 14:      PetscMap - Abstract PETSc object that defines the layout of vector and
 15:   matrices across processors

 17:    Level: advanced

 19:    Notes:
 20:     Does not play a role in the PETSc design, can be ignored

 22:   Concepts: parallel decomposition

 24: .seealso:  PetscMapCreateMPI()
 25: S*/
 26: typedef struct _p_PetscMap*         PetscMap;

 28: #define MAP_SEQ "seq"
 29: #define MAP_MPI "mpi"
 30: #define PetscMapType const char*

 32: /* Logging support */

 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);

 44: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapSetUp(PetscMap);
 45: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscMapView(PetscMap,PetscViewer);

 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*[]);

 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 *[]);

 60: /* Dynamic creation and loading functions */
 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

 75: /*S
 76:      Vec - Abstract PETSc vector object

 78:    Level: beginner

 80:   Concepts: field variables, unknowns, arrays

 82: .seealso:  VecCreate(), VecType, VecSetType()
 83: S*/
 84: typedef struct _p_Vec*         Vec;

 86: /*S
 87:      VecScatter - Object used to manage communication of data
 88:        between vectors in parallel. Manages both scatters and gathers

 90:    Level: beginner

 92:   Concepts: scatter

 94: .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
 95: S*/
 96: typedef struct _p_VecScatter*  VecScatter;

 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()

103:    Level: beginner

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*

113: /* Logging support */
114: #define    VEC_FILE_COOKIE 1211214

123: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecInitializePackage(char *);

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);

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*[]);

145: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetSizes(Vec,PetscInt,PetscInt);

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*);

154: /*E
155:     NormType - determines what type of norm to compute

157:     Level: beginner

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;
163: #define NORM_MAX NORM_INFINITY

165: /*MC
166:      NORM_1 - the one norm, ||v|| = sum_i | v_i |. ||A|| = max_j || v_*j ||, maximum column sum

168:    Level: beginner

170: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_2, NORM_FROBENIUS, 
171:            NORM_INFINITY, NORM_1_AND_2

173: M*/

175: /*MC
176:      NORM_2 - the two norm, ||v|| = sqrt(sum_i (v_i)^2) (vectors only)

178:    Level: beginner

180: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_FROBENIUS, 
181:            NORM_INFINITY, NORM_1_AND_2

183: M*/

185: /*MC
186:      NORM_FROBENIUS - ||A|| = sqrt(sum_ij (A_ij)^2), same as NORM_2 for vectors

188:    Level: beginner

190: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
191:            NORM_INFINITY, NORM_1_AND_2

193: M*/

195: /*MC
196:      NORM_INFINITY - ||v|| = max_i |v_i|. ||A|| = max_i || v_i* ||, maximum row sum

198:    Level: beginner

200: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
201:            NORM_FROBINIUS, NORM_1_AND_2

203: M*/

205: /*MC
206:      NORM_1_AND_2 - computes both the 1 and 2 norm of a vector

208:    Level: beginner

210: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
211:            NORM_FROBINIUS, NORM_INFINITY

213: M*/

215: /*MC
216:      NORM_MAX - see NORM_INFINITY

218:    Level: beginner

220: M*/

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 VecNormComposedDataID(NormType,PetscInt*);
227: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormalize(Vec,PetscReal *);
228: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSum(Vec,PetscScalar*);
229: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMax(Vec,PetscInt*,PetscReal *);
230: PetscPolymorphicSubroutine(VecMax,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
231: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMin(Vec,PetscInt*,PetscReal *);
232: PetscPolymorphicSubroutine(VecMin,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
233: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScale(Vec v,PetscScalar a);
234: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec,Vec);
235: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec,PetscRandom);
236: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSet(Vec,PetscScalar);
237: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec,Vec);
238: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPY(Vec,PetscScalar,Vec);
239: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAXPBY(Vec,PetscScalar,PetscScalar,Vec);
240: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMAXPY(Vec,PetscInt,const PetscScalar[],Vec*);
241: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAYPX(Vec,PetscScalar,Vec);
242: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecWAXPY(Vec,PetscScalar,Vec,Vec);
243: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMax(Vec,Vec,Vec);
244: PetscPolymorphicSubroutine(VecPointwiseMax,(Vec x,Vec y),(x,y,y))
245: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMaxAbs(Vec,Vec,Vec);
246: PetscPolymorphicSubroutine(VecPointwiseMaxAbs,(Vec x,Vec y),(x,y,y))
247: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMin(Vec,Vec,Vec);
248: PetscPolymorphicSubroutine(VecPointwiseMin,(Vec x,Vec y),(x,y,y))
249: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMult(Vec,Vec,Vec);
250: PetscPolymorphicSubroutine(VecPointwiseMult,(Vec x,Vec y),(x,y,y))
251: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseDivide(Vec,Vec,Vec);
252: PetscPolymorphicSubroutine(VecPointwiseDivide,(Vec x,Vec y),(x,y,y))
253: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
254: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecShift(Vec,PetscScalar);
255: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecReciprocal(Vec);
256: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPermute(Vec, IS, PetscTruth);
257: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSqrt(Vec);
258: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAbs(Vec);
259: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicate(Vec,Vec*);
260: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicateVecs(Vec,PetscInt,Vec*[]);
261: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDestroyVecs(Vec[],PetscInt);
262: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetPetscMap(Vec,PetscMap*);
263: PetscPolymorphicFunction(VecGetPetscMap,(Vec x),(x,&y),PetscMap,y)
264: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideNormAll(Vec,NormType,PetscReal*);
265: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMaxAll(Vec,PetscInt *,PetscReal *);
266: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMinAll(Vec,PetscInt *,PetscReal *);
267: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScaleAll(Vec,PetscScalar*);

269: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideNorm(Vec,PetscInt,NormType,PetscReal*);
270: PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i),(x,i,NORM_2,&r),PetscReal,r)
271: PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i,NormType t),(x,i,t,&r),PetscReal,r)
272: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMax(Vec,PetscInt,PetscInt *,PetscReal *);
273: PetscPolymorphicFunction(VecStrideMax,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
274: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideMin(Vec,PetscInt,PetscInt *,PetscReal *);
275: PetscPolymorphicFunction(VecStrideMin,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
276: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScale(Vec,PetscInt,PetscScalar*);
277: PetscPolymorphicScalar(VecStrideScale,(Vec x,PetscInt i,PetscScalar _t),(x,i,&_T))
278: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGather(Vec,PetscInt,Vec,InsertMode);
279: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatter(Vec,PetscInt,Vec,InsertMode);
280: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideGatherAll(Vec,Vec*,InsertMode);
281: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStrideScatterAll(Vec*,Vec,InsertMode);

283: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValues(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
284: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetValues(Vec,PetscInt,const PetscInt[],PetscScalar[]);
285: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec);
286: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec);
287: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec,PetscInt,PetscInt);
288: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec,PetscViewer);
289: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec,PetscInt*,PetscInt*,PetscInt*,PetscInt*);

293: /*MC
294:    VecSetValue - Set a single entry into a vector.

296:    Synopsis:
297:    PetscErrorCode VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode);

299:    Not Collective

301:    Input Parameters:
302: +  v - the vector
303: .  row - the row location of the entry
304: .  value - the value to insert
305: -  mode - either INSERT_VALUES or ADD_VALUES

307:    Notes:
308:    For efficiency one should use VecSetValues() and set several or 
309:    many values simultaneously if possible.

311:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
312:    MUST be called after all calls to VecSetValues() have been completed.

314:    VecSetValues() uses 0-based indices in Fortran as well as in C.

316:    Level: beginner

318: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
319: M*/
320: #define VecSetValue(v,i,va,mode) ((VecSetValue_Row = i,VecSetValue_Value = va,0) || VecSetValues(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))

322: /*MC
323:    VecSetValueLocal - Set a single entry into a vector using the local numbering

325:    Synopsis:
326:    PetscErrorCode VecSetValueLocal(Vec v,int row,PetscScalar value, InsertMode mode);

328:    Not Collective

330:    Input Parameters:
331: +  v - the vector
332: .  row - the row location of the entry
333: .  value - the value to insert
334: -  mode - either INSERT_VALUES or ADD_VALUES

336:    Notes:
337:    For efficiency one should use VecSetValues() and set several or 
338:    many values simultaneously if possible.

340:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
341:    MUST be called after all calls to VecSetValues() have been completed.

343:    VecSetValues() uses 0-based indices in Fortran as well as in C.

345:    Level: beginner

347: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
348: M*/
349: #define VecSetValueLocal(v,i,va,mode) ((VecSetValue_Row = i,VecSetValue_Value = va,0) || VecSetValuesLocal(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))

351: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetBlockSize(Vec,PetscInt);
352: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec,PetscInt*);
353: PetscPolymorphicFunction(VecGetBlockSize,(Vec x),(x,&i),PetscInt,i)
354: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlocked(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);

356: /* Dynamic creation and loading functions */
359: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetType(Vec, VecType);
360: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetType(Vec, VecType *);
361: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegister(const char[],const char[],const char[],PetscErrorCode (*)(Vec));
362: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterAll(const char []);
363: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRegisterDestroy(void);

365: /*MC
366:   VecRegisterDynamic - Adds a new vector component implementation

368:   Synopsis:
369:   PetscErrorCode VecRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(Vec))

371:   Not Collective

373:   Input Parameters:
374: + name        - The name of a new user-defined creation routine
375: . path        - The path (either absolute or relative) of the library containing this routine
376: . func_name   - The name of routine to create method context
377: - create_func - The creation routine itself

379:   Notes:
380:   VecRegisterDynamic() may be called multiple times to add several user-defined vectors

382:   If dynamic libraries are used, then the fourth input argument (routine_create) is ignored.

384:   Sample usage:
385: .vb
386:     VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate);
387: .ve

389:   Then, your vector type can be chosen with the procedural interface via
390: .vb
391:     VecCreate(MPI_Comm, Vec *);
392:     VecSetType(Vec,"my_vector_name");
393: .ve
394:    or at runtime via the option
395: .vb
396:     -vec_type my_vector_name
397: .ve

399:   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
400:          If your function is not being put into a shared library then use VecRegister() instead
401:         
402:   Level: advanced

404: .keywords: Vec, register
405: .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister()
406: M*/
407: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
408: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
409: #else
410: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
411: #endif


414: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
415: PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is1,Vec y,IS is2),(x,is1,y,is2,&s),VecScatter,s)
416: PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,IS is,Vec y,VecScatter *s),(x,is,y,PETSC_NULL,s))
417: PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is,Vec y),(x,is,y,PETSC_NULL,&s),VecScatter,s)
418: PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,Vec y,IS is,VecScatter *s),(x,PETSC_NULL,y,is,s))
419: PetscPolymorphicFunction(VecScatterCreate,(Vec x,Vec y,IS is),(x,PETSC_NULL,y,is,&s),VecScatter,s)
420: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
421: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
422: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
423: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterDestroy(VecScatter);
424: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCopy(VecScatter,VecScatter *);
425: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterView(VecScatter,PetscViewer);
426: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterRemap(VecScatter,PetscInt *,PetscInt*);
427: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterGetMerged(VecScatter,PetscTruth*);

429: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray_Private(Vec,PetscScalar*[]);
430: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray_Private(Vec,PetscScalar*[]);
431: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
432: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
433: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
434: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
435: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
436: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
437: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
438: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);

440: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecPlaceArray(Vec,const PetscScalar[]);
441: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec);
442: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecReplaceArray(Vec,const PetscScalar[]);
443: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetArrays(const Vec[],PetscInt,PetscScalar**[]);
444: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArrays(const Vec[],PetscInt,PetscScalar**[]);

446: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecValid(Vec,PetscTruth*);
447: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec,PetscViewer);
448: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec, char *);
449: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecEqual(Vec,Vec,PetscTruth*);
450: PetscPolymorphicFunction(VecEqual,(Vec x,Vec y),(x,y,&s),PetscTruth,s)
451: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoad(PetscViewer,VecType,Vec*);
452: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer,Vec);

454: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec,PetscInt*);
455: PetscPolymorphicFunction(VecGetSize,(Vec x),(x,&s),PetscInt,s)
456: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec,PetscInt*);
457: PetscPolymorphicFunction(VecGetLocalSize,(Vec x),(x,&s),PetscInt,s)
458: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec,PetscInt*,PetscInt*);

460: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
461: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
462: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
463: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlockedLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);

465: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotBegin(Vec,Vec,PetscScalar *);
466: PetscPolymorphicSubroutine(VecDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
467: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecDotEnd(Vec,Vec,PetscScalar *);
468: PetscPolymorphicFunction(VecDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
469: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotBegin(Vec,Vec,PetscScalar *);
470: PetscPolymorphicSubroutine(VecTDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
471: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecTDotEnd(Vec,Vec,PetscScalar *);
472: PetscPolymorphicFunction(VecTDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
473: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormBegin(Vec,NormType,PetscReal *);
474: PetscPolymorphicSubroutine(VecNormBegin,(Vec x,NormType t),(x,t,PETSC_NULL))
475: PetscPolymorphicSubroutine(VecNormBegin,(Vec x),(x,NORM_2,PETSC_NULL))
476: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecNormEnd(Vec,NormType,PetscReal *);
477: PetscPolymorphicFunction(VecNormEnd,(Vec x,NormType t),(x,t,&s),PetscReal,s)
478: PetscPolymorphicFunction(VecNormEnd,(Vec x),(x,NORM_2,&s),PetscReal,s)

480: typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption;
481: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec,VecOption);

483: /*
484:    Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function
485:    call overhead on any 'native' Vecs.
486: */
487:  #include vecimpl.h

489: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecContourScale(Vec,PetscReal,PetscReal);

491: /*
492:     These numbers need to match the entries in 
493:   the function table in vecimpl.h
494: */
495: typedef enum { VECOP_VIEW = 32,
496:                VECOP_LOADINTOVECTOR = 38
497:              } VecOperation;
498: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec,VecOperation,void(*)(void));

500: /*
501:      Routines for dealing with ghosted vectors:
502:   vectors with ghost elements at the end of the array.
503: */
504: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhost(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
505: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
506: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlock(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
507: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecCreateGhostBlockWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
508: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostGetLocalForm(Vec,Vec*);
509: PetscPolymorphicFunction(VecGhostGetLocalForm,(Vec x),(x,&s),Vec,s)
510: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostRestoreLocalForm(Vec,Vec*);
511: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
512: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);

514: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec);

516: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToAll(Vec,VecScatter*,Vec*);
517: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT VecScatterCreateToZero(Vec,VecScatter*,Vec*);

519: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaGetVector(PetscViewer, Vec);
520: EXTERN PetscErrorCode PETSCVEC_DLLEXPORT PetscViewerMathematicaPutVector(PetscViewer, Vec);

522: /*S
523:      Vecs - Collection of vectors where the data for the vectors is stored in 
524:             one continquous memory

526:    Level: advanced

528:    Notes:
529:     Temporary construct for handling multiply right hand side solves

531:     This is faked by storing a single vector that has enough array space for 
532:     n vectors

534:   Concepts: parallel decomposition

536: S*/
537:         struct _p_Vecs  {PetscInt n; Vec v;};
538: typedef struct _p_Vecs* Vecs;
539: #define VecsDestroy(x)            (VecDestroy((x)->v)         || PetscFree(x))
540: #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
541: #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
542: #define VecsDuplicate(x,y)        (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))


546: #endif