Actual source code: petscvec.h

  1: /* $Id: petscvec.h,v 1.118 2001/04/18 14:36:07 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: #define VEC_COOKIE         PETSC_COOKIE+3
 14: #define MAP_COOKIE         PETSC_COOKIE+22
 15: #define VEC_SCATTER_COOKIE PETSC_COOKIE+4

 17: /*S
 18:      Map - Abstract PETSc object that defines the layout of vector and
 19:   matrices across processors

 21:    Level: advanced

 23:    Notes:
 24:     Does not play a role in the PETSc design, can be ignored

 26:   Concepts: parallel decomposition

 28: .seealso:  MapCreateMPI()
 29: S*/
 30: typedef struct _p_Map*         Map;

 32: /*S
 33:      Vec - Abstract PETSc vector object

 35:    Level: beginner

 37:   Concepts: field variables, unknowns, arrays

 39: .seealso:  VecCreate(), VecType, VecSetType()
 40: S*/
 41: typedef struct _p_Vec*         Vec;

 43: /*S
 44:      VecScatter - Object used to manage communication of data
 45:        between vectors in parallel. Manages both scatters and gathers

 47:    Level: beginner

 49:   Concepts: scatter

 51: .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
 52: S*/
 53: typedef struct _p_VecScatter*  VecScatter;

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

 60:    Level: beginner

 62: .seealso: VecSetType(), Vec
 63: E*/
 64: #define VEC_SEQ    "seq"
 65: #define VEC_MPI    "mpi"
 66: #define VEC_FETI   "feti"
 67: #define VEC_SHARED "shared"
 68: typedef char*                  VecType;

 70: EXTERN int VecCreateSeq(MPI_Comm,int,Vec*);
 71: EXTERN int MapCreateMPI(MPI_Comm,int,int,Map*);
 72: EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*);
 73: EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const Scalar[],Vec*);
 74: EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const Scalar[],Vec*);
 75: EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*);
 76: EXTERN int VecCreate(MPI_Comm,int,int,Vec*);
 77: EXTERN int VecSetType(Vec,VecType);
 78: EXTERN int VecSetFromOptions(Vec);

 80: EXTERN int VecDestroy(Vec);

 82: EXTERN int MapDestroy(Map);
 83: EXTERN int MapGetLocalSize(Map,int *);
 84: EXTERN int MapGetSize(Map,int *);
 85: EXTERN int MapGetLocalRange(Map,int *,int *);
 86: EXTERN int MapGetGlobalRange(Map,int *[]);

 88: EXTERN int VecDot(Vec,Vec,Scalar*);
 89: EXTERN int VecTDot(Vec,Vec,Scalar*);
 90: EXTERN int VecMDot(int,Vec,const Vec[],Scalar*);
 91: EXTERN int VecMTDot(int,Vec,const Vec[],Scalar*);

 93: /*E
 94:     NormType - determines what type of norm to compute

 96:     Level: beginner

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

103: EXTERN int VecNorm(Vec,NormType,PetscReal *);
104: EXTERN int VecSum(Vec,Scalar*);
105: EXTERN int VecMax(Vec,int*,PetscReal *);
106: EXTERN int VecMin(Vec,int*,PetscReal *);
107: EXTERN int VecScale(const Scalar*,Vec);
108: EXTERN int VecCopy(Vec,Vec);
109: EXTERN int VecSetRandom(PetscRandom,Vec);
110: EXTERN int VecSet(const Scalar*,Vec);
111: EXTERN int VecSwap(Vec,Vec);
112: EXTERN int VecAXPY(const Scalar*,Vec,Vec);
113: EXTERN int VecAXPBY(const Scalar*,const Scalar *,Vec,Vec);
114: EXTERN int VecMAXPY(int,const Scalar*,Vec,Vec*);
115: EXTERN int VecAYPX(const Scalar*,Vec,Vec);
116: EXTERN int VecWAXPY(const Scalar*,Vec,Vec,Vec);
117: EXTERN int VecPointwiseMult(Vec,Vec,Vec);
118: EXTERN int VecPointwiseDivide(Vec,Vec,Vec);
119: EXTERN int VecShift(const Scalar*,Vec);
120: EXTERN int VecReciprocal(Vec);
121: EXTERN int VecAbs(Vec);
122: EXTERN int VecDuplicate(Vec,Vec*);
123: EXTERN int VecDuplicateVecs(Vec,int,Vec*[]);
124: EXTERN int VecDestroyVecs(const Vec[],int);
125: EXTERN int VecGetMap(Vec,Map*);

127: /*E
128:     InsertMode - Whether entries are inserted or added into vectors or matrices
129:      to continue to add values to it

131:     Level: beginner

133: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
134:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
135:           MatSetValuesBlockedLocal(), MatSetValuesLocal()
136: E*/
137: typedef enum {NOT_SET_VALUES,INSERT_VALUES,ADD_VALUES,MAX_VALUES} InsertMode;

139: EXTERN int VecStrideNorm(Vec,int,NormType,double*);
140: EXTERN int VecStrideGather(Vec,int,Vec,InsertMode);
141: EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode);
142: EXTERN int VecStrideMax(Vec,int,int *,double *);
143: EXTERN int VecStrideMin(Vec,int,int *,double *);
144: EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode);
145: EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode);

147: EXTERN int VecSetValues(Vec,int,const int[],const Scalar[],InsertMode);
148: EXTERN int VecAssemblyBegin(Vec);
149: EXTERN int VecAssemblyEnd(Vec);
150: EXTERN int VecSetStashInitialSize(Vec,int,int);
151: EXTERN int VecStashView(Vec,PetscViewer);

153: #define VecSetValue(v,i,va,mode) 
154: {int _ierr,_row = i; Scalar _va = va; 
155:   _VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr); 
156: }
157: EXTERN int VecSetBlockSize(Vec,int);
158: EXTERN int VecGetBlockSize(Vec,int*);
159: EXTERN int VecSetValuesBlocked(Vec,int,const int[],const Scalar[],InsertMode);

161: extern PetscTruth VecRegisterAllCalled;
162: EXTERN int        VecRegisterAll(const char []);
163: EXTERN int        VecRegister(const char[],const char[],const char[],int(*)(Vec));
164: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
165: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
166: #else
167: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
168: #endif


171: /*E
172:     ScatterMode - Determines the direction of a scatter

174:    Level: beginner

176: .seealso: VecScatter, VecScatterBegin(), VecScatterEnd()
177: E*/
178: typedef enum {SCATTER_FORWARD=0,SCATTER_REVERSE=1,SCATTER_FORWARD_LOCAL=2,
179:               SCATTER_REVERSE_LOCAL=3,SCATTER_LOCAL=2} ScatterMode;
180: EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
181: EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
182: EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
183: EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
184: EXTERN int VecScatterDestroy(VecScatter);
185: EXTERN int VecScatterCopy(VecScatter,VecScatter *);
186: EXTERN int VecScatterView(VecScatter,PetscViewer);
187: EXTERN int VecScatterRemap(VecScatter,int *,int*);

189: typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection;
190: typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2,
191:               PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType;

193: typedef struct _p_VecPipeline*  VecPipeline;

195: EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *);
196: EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject);
197: EXTERN int VecPipelineSetup(VecPipeline);
198: EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
199: EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
200: EXTERN int VecPipelineView(VecPipeline,PetscViewer);
201: EXTERN int VecPipelineDestroy(VecPipeline);

203: EXTERN int VecGetArray(Vec,Scalar*[]);
204: EXTERN int VecRestoreArray(Vec,Scalar*[]);
205: EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,Scalar****[]);
206: EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,Scalar****[]);
207: EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,Scalar***[]);
208: EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,Scalar***[]);
209: EXTERN int VecGetArray2d(Vec,int,int,int,int,Scalar**[]);
210: EXTERN int VecRestoreArray2d(Vec,int,int,int,int,Scalar**[]);
211: EXTERN int VecGetArray1d(Vec,int,int,Scalar *[]);
212: EXTERN int VecRestoreArray1d(Vec,int,int,Scalar *[]);

214: EXTERN int VecPlaceArray(Vec,const Scalar[]);
215: EXTERN int VecResetArray(Vec);
216: EXTERN int VecReplaceArray(Vec,const Scalar[]);
217: EXTERN int VecGetArrays(const Vec[],int,Scalar**[]);
218: EXTERN int VecRestoreArrays(const Vec[],int,Scalar**[]);

220: EXTERN int VecValid(Vec,PetscTruth*);
221: EXTERN int VecView(Vec,PetscViewer);
222: EXTERN int VecEqual(Vec,Vec,PetscTruth*);
223: EXTERN int VecLoad(PetscViewer,Vec*);
224: EXTERN int VecLoadIntoVector(PetscViewer,Vec);

226: EXTERN int VecGetSize(Vec,int*);
227: EXTERN int VecGetType(Vec,VecType*);
228: EXTERN int VecGetLocalSize(Vec,int*);
229: EXTERN int VecGetOwnershipRange(Vec,int*,int*);

231: EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
232: EXTERN int VecSetValuesLocal(Vec,int,const int[],const Scalar[],InsertMode);
233: EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
234: EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const Scalar[],InsertMode);

236: EXTERN int VecDotBegin(Vec,Vec,Scalar *);
237: EXTERN int VecDotEnd(Vec,Vec,Scalar *);
238: EXTERN int VecTDotBegin(Vec,Vec,Scalar *);
239: EXTERN int VecTDotEnd(Vec,Vec,Scalar *);
240: EXTERN int VecNormBegin(Vec,NormType,double *);
241: EXTERN int VecNormEnd(Vec,NormType,double *);

243: typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES} VecOption;
244: EXTERN int VecSetOption(Vec,VecOption);

246: EXTERN int VecContourScale(Vec,double,double);

248: /*
249:     These numbers need to match the entries in 
250:   the function table in src/vec/vecimpl.h
251: */
252: typedef enum { VECOP_VIEW = 33,
253:                VECOP_LOADINTOVECTOR = 40
254:              } VecOperation;
255: EXTERN int VecSetOperation(Vec,VecOperation,void(*)());

257: /*
258:      Routines for dealing with ghosted vectors:
259:   vectors with ghost elements at the end of the array.
260: */
261: EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*);
262: EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const Scalar[],Vec*);
263: EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*);
264: EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const Scalar[],Vec*);
265: EXTERN int VecGhostGetLocalForm(Vec,Vec*);
266: EXTERN int VecGhostRestoreLocalForm(Vec,Vec*);
267: EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
268: EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);

270: EXTERN int VecConjugate(Vec);

272: #endif