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 PetscMapSetType(PetscMap,PetscMapType);
 42: EXTERN int PetscMapGetType(PetscMap,PetscMapType *);
 43: EXTERN int PetscMapSetSerializeType(PetscMap,PetscMapSerializeType);
 44: EXTERN int PetscMapGetSerializeType(PetscMap,PetscMapSerializeType *);
 45: EXTERN int PetscMapSetFromOptions(PetscMap);
 46: EXTERN int PetscMapPrintHelp(PetscMap);
 47: EXTERN int PetscMapDestroy(PetscMap);

 49: EXTERN int PetscMapSetLocalSize(PetscMap,int);
 50: EXTERN int PetscMapGetLocalSize(PetscMap,int *);
 51: EXTERN int PetscMapSetSize(PetscMap,int);
 52: EXTERN int PetscMapGetSize(PetscMap,int *);
 53: EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *);
 54: EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]);

 56: /* Dynamic creation and loading functions */
 57: extern PetscFList PetscMapList;
 58: extern PetscTruth PetscMapRegisterAllCalled;
 59: EXTERN int PetscMapSetType(PetscMap, PetscMapType);
 60: EXTERN int PetscMapGetType(PetscMap, PetscMapType *);
 61: EXTERN int PetscMapRegister(const char[],const char[],const char[],int(*)(PetscMap));
 62: EXTERN int PetscMapRegisterAll(const char []);
 63: EXTERN int PetscMapRegisterDestroy(void);
 64: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
 65: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0)
 66: #else
 67: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d)
 68: #endif

 70: extern PetscFList PetscMapSerializeList;
 71: extern PetscTruth PetscMapSerializeRegisterAllCalled;
 72: EXTERN int PetscMapSetSerializeType(PetscMap, PetscMapSerializeType);
 73: EXTERN int PetscMapGetSerializeType(PetscMap, PetscMapSerializeType *);
 74: EXTERN int PetscMapSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, PetscMap *, PetscViewer, PetscTruth));
 75: EXTERN int PetscMapSerializeRegisterAll(const char []);
 76: EXTERN int PetscMapSerializeRegisterDestroy(void);
 77: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
 78: #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,0)
 79: #else
 80: #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,d)
 81: #endif

 83: /*S
 84:      Vec - Abstract PETSc vector object

 86:    Level: beginner

 88:   Concepts: field variables, unknowns, arrays

 90: .seealso:  VecCreate(), VecType, VecSetType()
 91: S*/
 92: typedef struct _p_Vec*         Vec;

 94: /*S
 95:      VecScatter - Object used to manage communication of data
 96:        between vectors in parallel. Manages both scatters and gathers

 98:    Level: beginner

100:   Concepts: scatter

102: .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
103: S*/
104: typedef struct _p_VecScatter*  VecScatter;

106: /*E
107:     VecType - String with the name of a PETSc vector or the creation function
108:        with an optional dynamic library name, for example
109:        http://www.mcs.anl.gov/petsc/lib.a:myveccreate()

111:    Level: beginner

113: .seealso: VecSetType(), Vec
114: E*/
115: #define VECSEQ         "seq"
116: #define VECMPI         "mpi"
117: #define VECFETI        "feti"
118: #define VECSHARED      "shared"
119: #define VECESI         "esi"
120: #define VECPETSCESI    "petscesi"
121: typedef char*  VecType;

123: #define VEC_SER_SEQ_BINARY "seq_binary"
124: #define VEC_SER_MPI_BINARY "mpi_binary"
125: typedef char *VecSerializeType;

127: /* Logging support */
128: #define    VEC_FILE_COOKIE 1211214
129: extern int VEC_COOKIE;
130: extern int VEC_SCATTER_COOKIE;
131: extern int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier;
132: extern int VEC_Norm, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin;
133: extern int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd;
134: extern int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication;

136: EXTERN int VecInitializePackage(char *);

138: EXTERN int VecCreate(MPI_Comm,Vec *);
139: EXTERN int VecCreateSeq(MPI_Comm,int,Vec*);
140: EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*);
141: EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*);
142: EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*);
143: EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*);
144: EXTERN int VecSerialize(MPI_Comm,Vec *,PetscViewer,PetscTruth);
145: EXTERN int VecSetType(Vec,VecType);
146: EXTERN int VecGetType(Vec,VecType *);
147: EXTERN int VecSetSerializeType(Vec,VecSerializeType);
148: EXTERN int VecGetSerializeType(Vec,VecSerializeType *);
149: EXTERN int VecSetFromOptions(Vec);
150: EXTERN int VecPrintHelp(Vec);
151: EXTERN int VecDestroy(Vec);

153: EXTERN int VecSetSizes(Vec,int,int);

155: EXTERN int VecDot(Vec,Vec,PetscScalar*);
156: EXTERN int VecTDot(Vec,Vec,PetscScalar*);
157: EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*);
158: EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*);

160: /*E
161:     NormType - determines what type of norm to compute

163:     Level: beginner

165: .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
166: E*/
167: typedef enum {NORM_1=1,NORM_2=2,NORM_FROBENIUS=3,NORM_INFINITY=4,NORM_1_AND_2=5} NormType;
168: #define NORM_MAX NORM_INFINITY

170: EXTERN int VecNorm(Vec,NormType,PetscReal *);
171: EXTERN int VecSum(Vec,PetscScalar*);
172: EXTERN int VecMax(Vec,int*,PetscReal *);
173: EXTERN int VecMin(Vec,int*,PetscReal *);
174: EXTERN int VecScale(const PetscScalar *a,Vec v);
175: EXTERN int VecCopy(Vec,Vec);
176: EXTERN int VecSetRandom(PetscRandom,Vec);
177: EXTERN int VecSet(const PetscScalar*,Vec);
178: EXTERN int VecSwap(Vec,Vec);
179: EXTERN int VecAXPY(const PetscScalar*,Vec,Vec);
180: EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec);
181: EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*);
182: EXTERN int VecAYPX(const PetscScalar*,Vec,Vec);
183: EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec);
184: EXTERN int VecPointwiseMult(Vec,Vec,Vec);
185: EXTERN int VecPointwiseDivide(Vec,Vec,Vec);
186: EXTERN int VecShift(const PetscScalar*,Vec);
187: EXTERN int VecReciprocal(Vec);
188: EXTERN int VecPermute(Vec, IS, PetscTruth);
189: EXTERN int VecSqrt(Vec);
190: EXTERN int VecAbs(Vec);
191: EXTERN int VecDuplicate(Vec,Vec*);
192: EXTERN int VecDuplicateVecs(Vec,int,Vec*[]);
193: EXTERN int VecDestroyVecs(const Vec[],int);
194: EXTERN int VecGetPetscMap(Vec,PetscMap*);

196: EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*);
197: EXTERN int VecStrideGather(Vec,int,Vec,InsertMode);
198: EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode);
199: EXTERN int VecStrideMax(Vec,int,int *,PetscReal *);
200: EXTERN int VecStrideMin(Vec,int,int *,PetscReal *);
201: EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode);
202: EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode);

204: EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode);
205: EXTERN int VecAssemblyBegin(Vec);
206: EXTERN int VecAssemblyEnd(Vec);
207: EXTERN int VecSetStashInitialSize(Vec,int,int);
208: EXTERN int VecStashView(Vec,PetscViewer);

210: #define VecSetValue(v,i,va,mode) 0;
211: {int _ierr,_row = i; PetscScalar _va = va; 
212:   _VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr); 
213: }
214: EXTERN int VecSetBlockSize(Vec,int);
215: EXTERN int VecGetBlockSize(Vec,int*);
216: EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode);

218: /* Dynamic creation and loading functions */
219: extern PetscFList VecList;
220: extern PetscTruth VecRegisterAllCalled;
221: EXTERN int VecSetType(Vec, VecType);
222: EXTERN int VecGetType(Vec, VecType *);
223: EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec));
224: EXTERN int VecRegisterAll(const char []);
225: EXTERN int VecRegisterDestroy(void);
226: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
227: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
228: #else
229: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
230: #endif

232: extern PetscFList VecSerializeList;
233: extern PetscTruth VecSerializeRegisterAllCalled;
234: EXTERN int VecSetSerializeType(Vec, VecSerializeType);
235: EXTERN int VecGetSerializeType(Vec, VecSerializeType *);
236: EXTERN int VecSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, Vec *, PetscViewer, PetscTruth));
237: EXTERN int VecSerializeRegisterAll(const char []);
238: EXTERN int VecSerializeRegisterDestroy(void);
239: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
240: #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,0)
241: #else
242: #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,d)
243: #endif

245: EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
246: EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
247: EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
248: EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
249: EXTERN int VecScatterDestroy(VecScatter);
250: EXTERN int VecScatterCopy(VecScatter,VecScatter *);
251: EXTERN int VecScatterView(VecScatter,PetscViewer);
252: EXTERN int VecScatterRemap(VecScatter,int *,int*);

254: typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection;
255: typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2,
256:               PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType;

258: typedef struct _p_VecPipeline*  VecPipeline;

260: EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *);
261: EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject);
262: EXTERN int VecPipelineSetup(VecPipeline);
263: EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
264: EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
265: EXTERN int VecPipelineView(VecPipeline,PetscViewer);
266: EXTERN int VecPipelineDestroy(VecPipeline);

268: EXTERN int VecGetArray(Vec,PetscScalar*[]);
269: EXTERN int VecRestoreArray(Vec,PetscScalar*[]);
270: EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
271: EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
272: EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
273: EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
274: EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]);
275: EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]);
276: EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]);
277: EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]);

279: EXTERN int VecPlaceArray(Vec,const PetscScalar[]);
280: EXTERN int VecResetArray(Vec);
281: EXTERN int VecReplaceArray(Vec,const PetscScalar[]);
282: EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]);
283: EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]);

285: EXTERN int VecValid(Vec,PetscTruth*);
286: EXTERN int VecView(Vec,PetscViewer);
287: EXTERN int VecViewFromOptions(Vec, char *);
288: EXTERN int VecEqual(Vec,Vec,PetscTruth*);
289: EXTERN int VecLoad(PetscViewer,Vec*);
290: EXTERN int VecLoadIntoVector(PetscViewer,Vec);

292: EXTERN int VecGetSize(Vec,int*);
293: EXTERN int VecGetLocalSize(Vec,int*);
294: EXTERN int VecGetType(Vec,VecType*);
295: EXTERN int VecGetOwnershipRange(Vec,int*,int*);

297: EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
298: EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode);
299: EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
300: EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode);

302: EXTERN int VecDotBegin(Vec,Vec,PetscScalar *);
303: EXTERN int VecDotEnd(Vec,Vec,PetscScalar *);
304: EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *);
305: EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *);
306: EXTERN int VecNormBegin(Vec,NormType,PetscReal *);
307: EXTERN int VecNormEnd(Vec,NormType,PetscReal *);

309: typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption;
310: EXTERN int VecSetOption(Vec,VecOption);

312: EXTERN int VecContourScale(Vec,PetscReal,PetscReal);

314: /*
315:     These numbers need to match the entries in 
316:   the function table in src/vec/vecimpl.h
317: */
318: typedef enum { VECOP_VIEW = 32,
319:                VECOP_LOADINTOVECTOR = 38
320:              } VecOperation;
321: EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void));

323: /*
324:      Routines for dealing with ghosted vectors:
325:   vectors with ghost elements at the end of the array.
326: */
327: EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*);
328: EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*);
329: EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*);
330: EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*);
331: EXTERN int VecGhostGetLocalForm(Vec,Vec*);
332: EXTERN int VecGhostRestoreLocalForm(Vec,Vec*);
333: EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
334: EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);

336: EXTERN int VecConjugate(Vec);

338: EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout);
339: EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout);


342: EXTERN int VecESISetType(Vec,char*);
343: EXTERN int VecESISetFromOptions(Vec);

345: #endif