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
 12: PETSC_EXTERN_CXX_BEGIN

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

 18:    Level: advanced

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

 23:   Concepts: parallel decomposition

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

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

 33: /* Logging support */
 34: extern int MAP_COOKIE;

 36: EXTERN int PetscMapCreate(MPI_Comm,PetscMap*);
 37: EXTERN int PetscMapCreateMPI(MPI_Comm,int,int,PetscMap*);
 38: EXTERN int PetscMapSetFromOptions(PetscMap);
 39: EXTERN int PetscMapPrintHelp(PetscMap);
 40: EXTERN int PetscMapDestroy(PetscMap);

 42: EXTERN int PetscMapSetLocalSize(PetscMap,int);
 43: EXTERN int PetscMapGetLocalSize(PetscMap,int *);
 44: EXTERN int PetscMapSetSize(PetscMap,int);
 45: EXTERN int PetscMapGetSize(PetscMap,int *);
 46: EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *);
 47: EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]);

 49: /* Dynamic creation and loading functions */
 50: extern PetscFList PetscMapList;
 51: extern PetscTruth PetscMapRegisterAllCalled;
 52: EXTERN int PetscMapSetType(PetscMap, const PetscMapType);
 53: EXTERN int PetscMapGetType(PetscMap, PetscMapType *);
 54: EXTERN int PetscMapRegister(const char[],const char[],const char[],int(*)(PetscMap));
 55: EXTERN int PetscMapRegisterAll(const char []);
 56: EXTERN int PetscMapRegisterDestroy(void);
 57: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
 58: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0)
 59: #else
 60: #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d)
 61: #endif

 63: /*S
 64:      Vec - Abstract PETSc vector object

 66:    Level: beginner

 68:   Concepts: field variables, unknowns, arrays

 70: .seealso:  VecCreate(), VecType, VecSetType()
 71: S*/
 72: typedef struct _p_Vec*         Vec;

 74: /*S
 75:      VecScatter - Object used to manage communication of data
 76:        between vectors in parallel. Manages both scatters and gathers

 78:    Level: beginner

 80:   Concepts: scatter

 82: .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
 83: S*/
 84: typedef struct _p_VecScatter*  VecScatter;

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

 91:    Level: beginner

 93: .seealso: VecSetType(), Vec
 94: E*/
 95: #define VECSEQ         "seq"
 96: #define VECMPI         "mpi"
 97: #define VECFETI        "feti"
 98: #define VECSHARED      "shared"
 99: #define VECESI         "esi"
100: #define VECPETSCESI    "petscesi"
101: #define VecType char*

103: /* Logging support */
104: #define    VEC_FILE_COOKIE 1211214
105: extern int VEC_COOKIE;
106: extern int VEC_SCATTER_COOKIE;
107: extern int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier;
108: extern int VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin;
109: extern int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd;
110: extern int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication;

112: EXTERN int VecInitializePackage(char *);

114: EXTERN int VecCreate(MPI_Comm,Vec *);
115: EXTERN int VecCreateSeq(MPI_Comm,int,Vec*);
116: EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*);
117: EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*);
118: EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*);
119: EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*);
120: EXTERN int VecSetFromOptions(Vec);
121: EXTERN int VecPrintHelp(Vec);
122: EXTERN int VecDestroy(Vec);

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

126: EXTERN int VecDot(Vec,Vec,PetscScalar*);
127: EXTERN int VecTDot(Vec,Vec,PetscScalar*);
128: EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*);
129: EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*);

131: /*E
132:     NormType - determines what type of norm to compute

134:     Level: beginner

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

141: EXTERN int VecNorm(Vec,NormType,PetscReal *);
142: EXTERN int VecNormComposedDataID(NormType,int*);
143: EXTERN int VecNormalize(Vec,PetscReal *);
144: EXTERN int VecSum(Vec,PetscScalar*);
145: EXTERN int VecMax(Vec,int*,PetscReal *);
146: EXTERN int VecMin(Vec,int*,PetscReal *);
147: EXTERN int VecScale(const PetscScalar *a,Vec v);
148: EXTERN int VecCopy(Vec,Vec);
149: EXTERN int VecSetRandom(PetscRandom,Vec);
150: EXTERN int VecSet(const PetscScalar*,Vec);
151: EXTERN int VecSwap(Vec,Vec);
152: EXTERN int VecAXPY(const PetscScalar*,Vec,Vec);
153: EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec);
154: EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*);
155: EXTERN int VecAYPX(const PetscScalar*,Vec,Vec);
156: EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec);
157: EXTERN int VecPointwiseMult(Vec,Vec,Vec);
158: EXTERN int VecPointwiseDivide(Vec,Vec,Vec);
159: EXTERN int VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
160: EXTERN int VecShift(const PetscScalar*,Vec);
161: EXTERN int VecReciprocal(Vec);
162: EXTERN int VecPermute(Vec, IS, PetscTruth);
163: EXTERN int VecSqrt(Vec);
164: EXTERN int VecAbs(Vec);
165: EXTERN int VecDuplicate(Vec,Vec*);
166: EXTERN int VecDuplicateVecs(Vec,int,Vec*[]);
167: EXTERN int VecDestroyVecs(const Vec[],int);
168: EXTERN int VecGetPetscMap(Vec,PetscMap*);

170: EXTERN int VecStrideNormAll(Vec,NormType,PetscReal*);
171: EXTERN int VecStrideMaxAll(Vec,int *,PetscReal *);
172: EXTERN int VecStrideMinAll(Vec,int *,PetscReal *);
173: EXTERN int VecStrideScaleAll(Vec,PetscScalar*);

175: EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*);
176: EXTERN int VecStrideMax(Vec,int,int *,PetscReal *);
177: EXTERN int VecStrideMin(Vec,int,int *,PetscReal *);
178: EXTERN int VecStrideScale(Vec,int,PetscScalar*);
179: EXTERN int VecStrideGather(Vec,int,Vec,InsertMode);
180: EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode);
181: EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode);
182: EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode);

184: EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode);
185: EXTERN int VecAssemblyBegin(Vec);
186: EXTERN int VecAssemblyEnd(Vec);
187: EXTERN int VecSetStashInitialSize(Vec,int,int);
188: EXTERN int VecStashView(Vec,PetscViewer);

190: extern int         VecSetValue_Row;
191: extern PetscScalar VecSetValue_Value;
192: /*MC
193:    VecSetValue - Set a single entry into a vector.

195:    Synopsis:
196:    int VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode);

198:    Not Collective

200:    Input Parameters:
201: +  v - the vector
202: .  row - the row location of the entry
203: .  value - the value to insert
204: -  mode - either INSERT_VALUES or ADD_VALUES

206:    Notes:
207:    For efficiency one should use VecSetValues() and set several or 
208:    many values simultaneously if possible.

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

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

215:    Level: beginner

217: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
218: M*/
219: #define VecSetValue(v,i,va,mode) (VecSetValue_Row = i, VecSetValue_Value = va, VecSetValues(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))

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

224:    Synopsis:
225:    int VecSetValueLocal(Vec v,int row,PetscScalar value, InsertMode mode);

227:    Not Collective

229:    Input Parameters:
230: +  v - the vector
231: .  row - the row location of the entry
232: .  value - the value to insert
233: -  mode - either INSERT_VALUES or ADD_VALUES

235:    Notes:
236:    For efficiency one should use VecSetValues() and set several or 
237:    many values simultaneously if possible.

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

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

244:    Level: beginner

246: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
247: M*/
248: #define VecSetValueLocal(v,i,va,mode) (VecSetValue_Row = i,VecSetValue_Value = va,VecSetValuesLocal(v,1,&VecSetValue_Row,&VecSetValue_Value,mode))

250: EXTERN int VecSetBlockSize(Vec,int);
251: EXTERN int VecGetBlockSize(Vec,int*);
252: EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode);

254: /* Dynamic creation and loading functions */
255: extern PetscFList VecList;
256: extern PetscTruth VecRegisterAllCalled;
257: EXTERN int VecSetType(Vec, const VecType);
258: EXTERN int VecGetType(Vec, VecType *);
259: EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec));
260: EXTERN int VecRegisterAll(const char []);
261: EXTERN int VecRegisterDestroy(void);

263: /*MC
264:   VecRegisterDynamic - Adds a new vector component implementation

266:   Synopsis:
267:   VecRegisterDynamic(char *name, char *path, char *func_name, int (*create_func)(Vec))

269:   Not Collective

271:   Input Parameters:
272: + name        - The name of a new user-defined creation routine
273: . path        - The path (either absolute or relative) of the library containing this routine
274: . func_name   - The name of routine to create method context
275: - create_func - The creation routine itself

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

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

282:   Sample usage:
283: .vb
284:     VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate);
285: .ve

287:   Then, your vector type can be chosen with the procedural interface via
288: .vb
289:     VecCreate(MPI_Comm, Vec *);
290:     VecSetType(Vec,"my_vector_name");
291: .ve
292:    or at runtime via the option
293: .vb
294:     -vec_type my_vector_name
295: .ve

297:   Notes: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.
298:          If your function is not being put into a shared library then use VecRegister() instead
299:         
300:   Level: advanced

302: .keywords: Vec, register
303: .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister()
304: M*/
305: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
306: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
307: #else
308: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
309: #endif


312: EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
313: EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter);
314: EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter);
315: EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter);
316: EXTERN int VecScatterDestroy(VecScatter);
317: EXTERN int VecScatterCopy(VecScatter,VecScatter *);
318: EXTERN int VecScatterView(VecScatter,PetscViewer);
319: EXTERN int VecScatterRemap(VecScatter,int *,int*);

321: typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection;
322: typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2,
323:               PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType;

325: typedef struct _p_VecPipeline*  VecPipeline;

327: EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *);
328: EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject);
329: EXTERN int VecPipelineSetup(VecPipeline);
330: EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
331: EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline);
332: EXTERN int VecPipelineView(VecPipeline,PetscViewer);
333: EXTERN int VecPipelineDestroy(VecPipeline);

335: EXTERN int VecGetArray_Private(Vec,PetscScalar*[]);
336: EXTERN int VecRestoreArray_Private(Vec,PetscScalar*[]);
337: EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
338: EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]);
339: EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
340: EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]);
341: EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]);
342: EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]);
343: EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]);
344: EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]);

346: EXTERN int VecPlaceArray(Vec,const PetscScalar[]);
347: EXTERN int VecResetArray(Vec);
348: EXTERN int VecReplaceArray(Vec,const PetscScalar[]);
349: EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]);
350: EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]);

352: EXTERN int VecValid(Vec,PetscTruth*);
353: EXTERN int VecView(Vec,PetscViewer);
354: EXTERN int VecViewFromOptions(Vec, char *);
355: EXTERN int VecEqual(Vec,Vec,PetscTruth*);
356: EXTERN int VecLoad(PetscViewer,const VecType,Vec*);
357: EXTERN int VecLoadIntoVector(PetscViewer,Vec);

359: EXTERN int VecGetSize(Vec,int*);
360: EXTERN int VecGetLocalSize(Vec,int*);
361: EXTERN int VecGetOwnershipRange(Vec,int*,int*);

363: EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
364: EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode);
365: EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
366: EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode);

368: EXTERN int VecDotBegin(Vec,Vec,PetscScalar *);
369: EXTERN int VecDotEnd(Vec,Vec,PetscScalar *);
370: EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *);
371: EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *);
372: EXTERN int VecNormBegin(Vec,NormType,PetscReal *);
373: EXTERN int VecNormEnd(Vec,NormType,PetscReal *);

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

378: /*
379:    Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function
380:    call overhead on any 'native' Vecs.
381: */
382:  #include vecimpl.h

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

386: /*
387:     These numbers need to match the entries in 
388:   the function table in vecimpl.h
389: */
390: typedef enum { VECOP_VIEW = 32,
391:                VECOP_LOADINTOVECTOR = 38
392:              } VecOperation;
393: EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void));

395: /*
396:      Routines for dealing with ghosted vectors:
397:   vectors with ghost elements at the end of the array.
398: */
399: EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*);
400: EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*);
401: EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*);
402: EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*);
403: EXTERN int VecGhostGetLocalForm(Vec,Vec*);
404: EXTERN int VecGhostRestoreLocalForm(Vec,Vec*);
405: EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
406: EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);

408: EXTERN int VecConjugate(Vec);

410: EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout);
411: EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout);


414: EXTERN int VecESISetType(Vec,const char*);
415: EXTERN int VecESISetFromOptions(Vec);

417: EXTERN int PetscViewerMathematicaGetVector(PetscViewer, Vec);
418: EXTERN int PetscViewerMathematicaPutVector(PetscViewer, Vec);

420: /*S
421:      Vecs - Collection of vectors where the data for the vectors is stored in 
422:             one continquous memory

424:    Level: advanced

426:    Notes:
427:     Temporary construct for handling multiply right hand side solves

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

432:   Concepts: parallel decomposition

434: S*/
435:         struct _p_Vecs  {int n; Vec v;};
436: typedef struct _p_Vecs* Vecs;
437: #define VecsDestroy(x)            (VecDestroy((x)->v)         || PetscFree(x))
438: #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
439: #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
440: #define VecsDuplicate(x,y)        (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))


443: PETSC_EXTERN_CXX_END
444: #endif