Actual source code: petscvec.h
1: /* $Id: petscvec.h,v 1.127 2001/09/11 16:31:30 bsmith Exp $ */
2: /*
3: Defines the vector component of PETSc. Vectors generally represent
4: degrees of freedom for finite element/finite difference functions
5: on a grid. They have more mathematical structure then simple arrays.
6: */
8: #ifndef __PETSCVEC_H
10: #include petscis.h
11: #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: typedef char *PetscMapType;
32: #define MAP_SER_MPI_BINARY "mpi_binary"
33: typedef char *PetscMapSerializeType;
35: /* Logging support */
36: extern int MAP_COOKIE;
38: EXTERN int PetscMapCreate(MPI_Comm,PetscMap*);
39: EXTERN int PetscMapCreateMPI(MPI_Comm,int,int,PetscMap*);
40: EXTERN int PetscMapSerialize(MPI_Comm,PetscMap *,PetscViewer,PetscTruth);
41: EXTERN int PetscMapSetFromOptions(PetscMap);
42: EXTERN int PetscMapPrintHelp(PetscMap);
43: EXTERN int PetscMapDestroy(PetscMap);
45: EXTERN int PetscMapSetLocalSize(PetscMap,int);
46: EXTERN int PetscMapGetLocalSize(PetscMap,int *);
47: EXTERN int PetscMapSetSize(PetscMap,int);
48: EXTERN int PetscMapGetSize(PetscMap,int *);
49: EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *);
50: EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]);
52: /* Dynamic creation and loading functions */
53: extern PetscFList PetscMapList;
54: extern PetscTruth PetscMapRegisterAllCalled;
55: EXTERN int PetscMapSetType(PetscMap, PetscMapType);
56: EXTERN int PetscMapGetType(PetscMap, PetscMapType *);
57: EXTERN int PetscMapRegister(const char[],const char[],const char[],int(*)(PetscMap));
58: EXTERN int PetscMapRegisterAll(const char []);
59: EXTERN int PetscMapRegisterDestroy(void);
60: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
61: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0)
62: #else
63: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d)
64: #endif
66: extern PetscFList PetscMapSerializeList;
67: extern PetscTruth PetscMapSerializeRegisterAllCalled;
68: EXTERN int PetscMapSetSerializeType(PetscMap, PetscMapSerializeType);
69: EXTERN int PetscMapGetSerializeType(PetscMap, PetscMapSerializeType *);
70: EXTERN int PetscMapSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, PetscMap *, PetscViewer, PetscTruth));
71: EXTERN int PetscMapSerializeRegisterAll(const char []);
72: EXTERN int PetscMapSerializeRegisterDestroy(void);
73: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
74: #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,0)
75: #else
76: #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,d)
77: #endif
79: /*S
80: Vec - Abstract PETSc vector object
82: Level: beginner
84: Concepts: field variables, unknowns, arrays
86: .seealso: VecCreate(), VecType, VecSetType()
87: S*/
88: typedef struct _p_Vec* Vec;
90: /*S
91: VecScatter - Object used to manage communication of data
92: between vectors in parallel. Manages both scatters and gathers
94: Level: beginner
96: Concepts: scatter
98: .seealso: VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
99: S*/
100: typedef struct _p_VecScatter* VecScatter;
102: /*E
103: VecType - String with the name of a PETSc vector or the creation function
104: with an optional dynamic library name, for example
105: http://www.mcs.anl.gov/petsc/lib.a:myveccreate()
107: Level: beginner
109: .seealso: VecSetType(), Vec
110: E*/
111: #define VECSEQ "seq"
112: #define VECMPI "mpi"
113: #define VECFETI "feti"
114: #define VECSHARED "shared"
115: #define VECESI "esi"
116: #define VECPETSCESI "petscesi"
117: typedef char* VecType;
119: #define VEC_SER_SEQ_BINARY "seq_binary"
120: #define VEC_SER_MPI_BINARY "mpi_binary"
121: typedef char *VecSerializeType;
123: /* Logging support */
124: #define VEC_FILE_COOKIE 1211214
125: extern int VEC_COOKIE;
126: extern int VEC_SCATTER_COOKIE;
127: extern int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier;
128: extern int VEC_Norm, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin;
129: extern int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd;
130: extern int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication;
132: EXTERN int VecInitializePackage(char *);
134: EXTERN int VecCreate(MPI_Comm,Vec *);
135: EXTERN int VecCreateSeq(MPI_Comm,int,Vec*);
136: EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*);
137: EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*);
138: EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*);
139: EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*);
140: EXTERN int VecSerialize(MPI_Comm,Vec *,PetscViewer,PetscTruth);
141: EXTERN int VecSetFromOptions(Vec);
142: EXTERN int VecPrintHelp(Vec);
143: EXTERN int VecDestroy(Vec);
145: EXTERN int VecSetSizes(Vec,int,int);
147: EXTERN int VecDot(Vec,Vec,PetscScalar*);
148: EXTERN int VecTDot(Vec,Vec,PetscScalar*);
149: EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*);
150: EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*);
152: /*E
153: NormType - determines what type of norm to compute
155: Level: beginner
157: .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
158: E*/
159: typedef enum {NORM_1=1,NORM_2=2,NORM_FROBENIUS=3,NORM_INFINITY=4,NORM_1_AND_2=5} NormType;
160: #define NORM_MAX NORM_INFINITY
162: EXTERN int VecNorm(Vec,NormType,PetscReal *);
163: EXTERN int VecSum(Vec,PetscScalar*);
164: EXTERN int VecMax(Vec,int*,PetscReal *);
165: EXTERN int VecMin(Vec,int*,PetscReal *);
166: EXTERN int VecScale(const PetscScalar *a,Vec v);
167: EXTERN int VecCopy(Vec,Vec);
168: EXTERN int VecSetRandom(PetscRandom,Vec);
169: EXTERN int VecSet(const PetscScalar*,Vec);
170: EXTERN int VecSwap(Vec,Vec);
171: EXTERN int VecAXPY(const PetscScalar*,Vec,Vec);
172: EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec);
173: EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*);
174: EXTERN int VecAYPX(const PetscScalar*,Vec,Vec);
175: EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec);
176: EXTERN int VecPointwiseMult(Vec,Vec,Vec);
177: EXTERN int VecPointwiseDivide(Vec,Vec,Vec);
178: EXTERN int VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
179: EXTERN int VecShift(const PetscScalar*,Vec);
180: EXTERN int VecReciprocal(Vec);
181: EXTERN int VecPermute(Vec, IS, PetscTruth);
182: EXTERN int VecSqrt(Vec);
183: EXTERN int VecAbs(Vec);
184: EXTERN int VecDuplicate(Vec,Vec*);
185: EXTERN int VecDuplicateVecs(Vec,int,Vec*[]);
186: EXTERN int VecDestroyVecs(const Vec[],int);
187: EXTERN int VecGetPetscMap(Vec,PetscMap*);
189: EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*);
190: EXTERN int VecStrideGather(Vec,int,Vec,InsertMode);
191: EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode);
192: EXTERN int VecStrideMax(Vec,int,int *,PetscReal *);
193: EXTERN int VecStrideMin(Vec,int,int *,PetscReal *);
194: EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode);
195: EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode);
197: EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode);
198: EXTERN int VecAssemblyBegin(Vec);
199: EXTERN int VecAssemblyEnd(Vec);
200: EXTERN int VecSetStashInitialSize(Vec,int,int);
201: EXTERN int VecStashView(Vec,PetscViewer);
203: #define VecSetValue(v,i,va,mode) 0;
204: {int _ierr,_row = i; PetscScalar _va = va;
205: _VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr);
206: }
207: EXTERN int VecSetBlockSize(Vec,int);
208: EXTERN int VecGetBlockSize(Vec,int*);
209: EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode);
211: /* Dynamic creation and loading functions */
212: extern PetscFList VecList;
213: extern PetscTruth VecRegisterAllCalled;
214: EXTERN int VecSetType(Vec, VecType);
215: EXTERN int VecGetType(Vec, VecType *);
216: EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec));
217: EXTERN int VecRegisterAll(const char []);
218: EXTERN int VecRegisterDestroy(void);
219: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
220: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
221: #else
222: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
223: #endif
225: extern PetscFList VecSerializeList;
226: extern PetscTruth VecSerializeRegisterAllCalled;
227: EXTERN int VecSetSerializeType(Vec, VecSerializeType);
228: EXTERN int VecGetSerializeType(Vec, VecSerializeType *);
229: EXTERN int VecSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, Vec *, PetscViewer, PetscTruth));
230: EXTERN int VecSerializeRegisterAll(const char []);
231: EXTERN int VecSerializeRegisterDestroy(void);
232: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
233: #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,0)
234: #else
235: #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,d)
236: #endif
238: EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
239: EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
240: EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
241: EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
242: EXTERN int VecScatterDestroy(VecScatter);
243: EXTERN int VecScatterCopy(VecScatter,VecScatter *);
244: EXTERN int VecScatterView(VecScatter,PetscViewer);
245: EXTERN int VecScatterRemap(VecScatter,int *,int*);
247: typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection;
248: typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2,
249: PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType;
251: typedef struct _p_VecPipeline* VecPipeline;
253: EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *);
254: EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject);
255: EXTERN int VecPipelineSetup(VecPipeline);
256: EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
257: EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
258: EXTERN int VecPipelineView(VecPipeline,PetscViewer);
259: EXTERN int VecPipelineDestroy(VecPipeline);
261: EXTERN int VecGetArray(Vec,PetscScalar*[]);
262: EXTERN int VecRestoreArray(Vec,PetscScalar*[]);
263: EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
264: EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
265: EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
266: EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
267: EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]);
268: EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]);
269: EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]);
270: EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]);
272: EXTERN int VecPlaceArray(Vec,const PetscScalar[]);
273: EXTERN int VecResetArray(Vec);
274: EXTERN int VecReplaceArray(Vec,const PetscScalar[]);
275: EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]);
276: EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]);
278: EXTERN int VecValid(Vec,PetscTruth*);
279: EXTERN int VecView(Vec,PetscViewer);
280: EXTERN int VecViewFromOptions(Vec, char *);
281: EXTERN int VecEqual(Vec,Vec,PetscTruth*);
282: EXTERN int VecLoad(PetscViewer,Vec*);
283: EXTERN int VecLoadIntoVector(PetscViewer,Vec);
285: EXTERN int VecGetSize(Vec,int*);
286: EXTERN int VecGetLocalSize(Vec,int*);
287: EXTERN int VecGetOwnershipRange(Vec,int*,int*);
289: EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
290: EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode);
291: EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
292: EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode);
294: EXTERN int VecDotBegin(Vec,Vec,PetscScalar *);
295: EXTERN int VecDotEnd(Vec,Vec,PetscScalar *);
296: EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *);
297: EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *);
298: EXTERN int VecNormBegin(Vec,NormType,PetscReal *);
299: EXTERN int VecNormEnd(Vec,NormType,PetscReal *);
301: typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption;
302: EXTERN int VecSetOption(Vec,VecOption);
304: EXTERN int VecContourScale(Vec,PetscReal,PetscReal);
306: /*
307: These numbers need to match the entries in
308: the function table in src/vec/vecimpl.h
309: */
310: typedef enum { VECOP_VIEW = 32,
311: VECOP_LOADINTOVECTOR = 38
312: } VecOperation;
313: EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void));
315: /*
316: Routines for dealing with ghosted vectors:
317: vectors with ghost elements at the end of the array.
318: */
319: EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*);
320: EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*);
321: EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*);
322: EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*);
323: EXTERN int VecGhostGetLocalForm(Vec,Vec*);
324: EXTERN int VecGhostRestoreLocalForm(Vec,Vec*);
325: EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
326: EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);
328: EXTERN int VecConjugate(Vec);
330: EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout);
331: EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout);
334: EXTERN int VecESISetType(Vec,char*);
335: EXTERN int VecESISetFromOptions(Vec);
337: EXTERN int PetscViewerMathematicaGetVector(PetscViewer, Vec);
338: EXTERN int PetscViewerMathematicaPutVector(PetscViewer, Vec);
340: /*S
341: Vecs - Collection of vectors where the data for the vectors is stored in
342: one continquous memory
344: Level: advanced
346: Notes:
347: Temporary construct for handling multiply right hand side solves
349: This is faked by storing a single vector that has enough array space for
350: n vectors
352: Concepts: parallel decomposition
354: S*/
355: struct _p_Vecs {int n; Vec v;};
356: typedef struct _p_Vecs* Vecs;
357: #define VecsDestroy(x) (VecDestroy((x)->v) || PetscFree(x))
358: #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
359: #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
360: #define VecsDuplicate(x,y) (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))
361: #endif