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

 11: PETSC_EXTERN_CXX_BEGIN

 13: /*S
 14:      Vec - Abstract PETSc vector object

 16:    Level: beginner

 18:   Concepts: field variables, unknowns, arrays

 20: .seealso:  VecCreate(), VecType, VecSetType()
 21: S*/
 22: typedef struct _p_Vec*         Vec;

 24: /*S
 25:      VecScatter - Object used to manage communication of data
 26:        between vectors in parallel. Manages both scatters and gathers

 28:    Level: beginner

 30:   Concepts: scatter

 32: .seealso:  VecScatterCreate(), VecScatterBegin(), VecScatterEnd()
 33: S*/
 34: typedef struct _p_VecScatter*  VecScatter;

 36: /*E
 37:   ScatterMode - Determines the direction of a scatter

 39:   Level: beginner

 41: .seealso: VecScatter, VecScatterBegin(), VecScatterEnd()
 42: E*/
 43: typedef enum {SCATTER_FORWARD=0, SCATTER_REVERSE=1, SCATTER_FORWARD_LOCAL=2, SCATTER_REVERSE_LOCAL=3, SCATTER_LOCAL=2} ScatterMode;

 45: /*MC
 46:     SCATTER_FORWARD - Scatters the values as dictated by the VecScatterCreate() call

 48:     Level: beginner

 50: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
 51:           SCATTER_REVERSE_LOCAL

 53: M*/

 55: /*MC
 56:     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
 57:          in the VecScatterCreate()

 59:     Level: beginner

 61: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
 62:           SCATTER_REVERSE_LOCAL

 64: M*/

 66: /*MC
 67:     SCATTER_FORWARD_LOCAL - Scatters the values as dictated by the VecScatterCreate() call except NO parallel communication
 68:        is done. Any variables that have be moved between processes are ignored

 70:     Level: developer

 72: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
 73:           SCATTER_REVERSE_LOCAL

 75: M*/

 77: /*MC
 78:     SCATTER_REVERSE_LOCAL - Moves the values in the opposite direction then the directions indicated in
 79:          in the VecScatterCreate()  except NO parallel communication
 80:        is done. Any variables that have be moved between processes are ignored

 82:     Level: developer

 84: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
 85:           SCATTER_REVERSE

 87: M*/

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

 94:    Level: beginner

 96: .seealso: VecSetType(), Vec
 97: J*/
 98: #define VecType char*
 99: #define VECSEQ         "seq"
100: #define VECMPI         "mpi"
101: #define VECSTANDARD    "standard"   /* seq on one process and mpi on several */
102: #define VECSHARED      "shared"
103: #define VECSIEVE       "sieve"
104: #define VECSEQCUSP     "seqcusp"
105: #define VECMPICUSP     "mpicusp"
106: #define VECCUSP        "cusp"       /* seqcusp on one process and mpicusp on several */
107: #define VECNEST        "nest"
108: #define VECSEQPTHREAD  "seqpthread"
109: #define VECPTHREAD     "pthread"    /* seqpthread on one process and mpipthread on several */

111: /* Logging support */
112: #define    VEC_FILE_CLASSID 1211214
113: extern  PetscClassId VEC_CLASSID;
114: extern  PetscClassId VEC_SCATTER_CLASSID;


117: extern PetscErrorCode  VecInitializePackage(const char[]);
118: extern PetscErrorCode  VecFinalizePackage(void);

120: extern PetscErrorCode  VecCreate(MPI_Comm,Vec*);
121: PetscPolymorphicSubroutine(VecCreate,(Vec *x),(PETSC_COMM_SELF,x))
122: extern PetscErrorCode  VecCreateSeq(MPI_Comm,PetscInt,Vec*);
123: PetscPolymorphicSubroutine(VecCreateSeq,(PetscInt n,Vec *x),(PETSC_COMM_SELF,n,x))
124: extern PetscErrorCode  VecCreateMPI(MPI_Comm,PetscInt,PetscInt,Vec*);
125: PetscPolymorphicSubroutine(VecCreateMPI,(PetscInt n,PetscInt N,Vec *x),(PETSC_COMM_WORLD,n,N,x))
126: extern PetscErrorCode  VecCreateSeqWithArray(MPI_Comm,PetscInt,const PetscScalar[],Vec*);
127: PetscPolymorphicSubroutine(VecCreateSeqWithArray,(PetscInt n,PetscScalar s[],Vec *x),(PETSC_COMM_SELF,n,s,x))
128: extern PetscErrorCode  VecCreateMPIWithArray(MPI_Comm,PetscInt,PetscInt,const PetscScalar[],Vec*);
129: PetscPolymorphicSubroutine(VecCreateMPIWithArray,(PetscInt n,PetscInt N,PetscScalar s[],Vec *x),(PETSC_COMM_WORLD,n,N,s,x))
130: extern PetscErrorCode  VecCreateShared(MPI_Comm,PetscInt,PetscInt,Vec*);
131: extern PetscErrorCode  VecSetFromOptions(Vec);
132: extern PetscErrorCode  VecSetUp(Vec);
133: extern PetscErrorCode  VecDestroy(Vec*);
134: extern PetscErrorCode  VecZeroEntries(Vec);
135: extern PetscErrorCode  VecSetOptionsPrefix(Vec,const char[]);
136: extern PetscErrorCode  VecAppendOptionsPrefix(Vec,const char[]);
137: extern PetscErrorCode  VecGetOptionsPrefix(Vec,const char*[]);

139: extern PetscErrorCode  VecSetSizes(Vec,PetscInt,PetscInt);

141: extern PetscErrorCode  VecDotNorm2(Vec,Vec,PetscScalar*,PetscScalar*);
142: extern PetscErrorCode  VecDot(Vec,Vec,PetscScalar*);
143: PetscPolymorphicFunction(VecDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
144: extern PetscErrorCode  VecTDot(Vec,Vec,PetscScalar*);
145: PetscPolymorphicFunction(VecTDot,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
146: extern PetscErrorCode  VecMDot(Vec,PetscInt,const Vec[],PetscScalar[]);
147: extern PetscErrorCode  VecMTDot(Vec,PetscInt,const Vec[],PetscScalar[]);
148: extern PetscErrorCode  VecGetSubVector(Vec,IS,Vec*);
149: extern PetscErrorCode  VecRestoreSubVector(Vec,IS,Vec*);

151: /*E
152:     NormType - determines what type of norm to compute

154:     Level: beginner

156: .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm()
157: E*/
158: typedef enum {NORM_1=0,NORM_2=1,NORM_FROBENIUS=2,NORM_INFINITY=3,NORM_1_AND_2=4} NormType;
159: extern const char *NormTypes[];
160: #define NORM_MAX NORM_INFINITY

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

165:    Level: beginner

167: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_2, NORM_FROBENIUS, 
168:            NORM_INFINITY, NORM_1_AND_2

170: M*/

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

175:    Level: beginner

177: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_FROBENIUS, 
178:            NORM_INFINITY, NORM_1_AND_2

180: M*/

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

185:    Level: beginner

187: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
188:            NORM_INFINITY, NORM_1_AND_2

190: M*/

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

195:    Level: beginner

197: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
198:            NORM_FROBINIUS, NORM_1_AND_2

200: M*/

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

205:    Level: beginner

207: .seealso:  NormType, MatNorm(), VecNorm(), VecNormBegin(), VecNormEnd(), NORM_1, NORM_2, 
208:            NORM_FROBINIUS, NORM_INFINITY

210: M*/

212: /*MC
213:      NORM_MAX - see NORM_INFINITY

215:    Level: beginner

217: M*/

219: extern PetscErrorCode  VecNorm(Vec,NormType,PetscReal *);
220: extern PetscErrorCode  VecNormAvailable(Vec,NormType,PetscBool *,PetscReal *);
221: PetscPolymorphicSubroutine(VecNorm,(Vec x,PetscReal *r),(x,NORM_2,r))
222: PetscPolymorphicFunction(VecNorm,(Vec x,NormType t),(x,t,&r),PetscReal,r)
223: PetscPolymorphicFunction(VecNorm,(Vec x),(x,NORM_2,&r),PetscReal,r)
224: extern PetscErrorCode  VecNormalize(Vec,PetscReal *);
225: extern PetscErrorCode  VecSum(Vec,PetscScalar*);
226: extern PetscErrorCode  VecMax(Vec,PetscInt*,PetscReal *);
227: PetscPolymorphicSubroutine(VecMax,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
228: extern PetscErrorCode  VecMin(Vec,PetscInt*,PetscReal *);
229: PetscPolymorphicSubroutine(VecMin,(Vec x,PetscReal *r),(x,PETSC_NULL,r))
230: extern PetscErrorCode  VecScale(Vec,PetscScalar);
231: extern PetscErrorCode  VecCopy(Vec,Vec);
232: extern PetscErrorCode  VecSetRandom(Vec,PetscRandom);
233: extern PetscErrorCode  VecSet(Vec,PetscScalar);
234: extern PetscErrorCode  VecSwap(Vec,Vec);
235: extern PetscErrorCode  VecAXPY(Vec,PetscScalar,Vec);
236: extern PetscErrorCode  VecAXPBY(Vec,PetscScalar,PetscScalar,Vec);
237: extern PetscErrorCode  VecMAXPY(Vec,PetscInt,const PetscScalar[],Vec[]);
238: extern PetscErrorCode  VecAYPX(Vec,PetscScalar,Vec);
239: extern PetscErrorCode  VecWAXPY(Vec,PetscScalar,Vec,Vec);
240: extern PetscErrorCode  VecAXPBYPCZ(Vec,PetscScalar,PetscScalar,PetscScalar,Vec,Vec);
241: extern PetscErrorCode  VecPointwiseMax(Vec,Vec,Vec);
242: PetscPolymorphicSubroutine(VecPointwiseMax,(Vec x,Vec y),(x,y,y))
243: extern PetscErrorCode  VecPointwiseMaxAbs(Vec,Vec,Vec);
244: PetscPolymorphicSubroutine(VecPointwiseMaxAbs,(Vec x,Vec y),(x,y,y))
245: extern PetscErrorCode  VecPointwiseMin(Vec,Vec,Vec);
246: PetscPolymorphicSubroutine(VecPointwiseMin,(Vec x,Vec y),(x,y,y))
247: extern PetscErrorCode  VecPointwiseMult(Vec,Vec,Vec);
248: PetscPolymorphicSubroutine(VecPointwiseMult,(Vec x,Vec y),(x,x,y))
249: extern PetscErrorCode  VecPointwiseDivide(Vec,Vec,Vec);
250: PetscPolymorphicSubroutine(VecPointwiseDivide,(Vec x,Vec y),(x,x,y))
251: extern PetscErrorCode  VecMaxPointwiseDivide(Vec,Vec,PetscReal*);
252: extern PetscErrorCode  VecShift(Vec,PetscScalar);
253: extern PetscErrorCode  VecReciprocal(Vec);
254: extern PetscErrorCode  VecPermute(Vec, IS, PetscBool );
255: extern PetscErrorCode  VecSqrtAbs(Vec);
256: extern PetscErrorCode  VecLog(Vec);
257: extern PetscErrorCode  VecExp(Vec);
258: extern PetscErrorCode  VecAbs(Vec);
259: extern PetscErrorCode  VecDuplicate(Vec,Vec*);
260: extern PetscErrorCode  VecDuplicateVecs(Vec,PetscInt,Vec*[]);
261: extern PetscErrorCode  VecDestroyVecs(PetscInt, Vec*[]);
262: extern PetscErrorCode  VecStrideNormAll(Vec,NormType,PetscReal[]);
263: extern PetscErrorCode  VecStrideMaxAll(Vec,PetscInt [],PetscReal []);
264: extern PetscErrorCode  VecStrideMinAll(Vec,PetscInt [],PetscReal []);
265: extern PetscErrorCode  VecStrideScaleAll(Vec,const PetscScalar[]);

267: extern PetscErrorCode  VecStrideNorm(Vec,PetscInt,NormType,PetscReal*);
268: PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i),(x,i,NORM_2,&r),PetscReal,r)
269: PetscPolymorphicFunction(VecStrideNorm,(Vec x,PetscInt i,NormType t),(x,i,t,&r),PetscReal,r)
270: extern PetscErrorCode  VecStrideMax(Vec,PetscInt,PetscInt *,PetscReal *);
271: PetscPolymorphicFunction(VecStrideMax,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
272: extern PetscErrorCode  VecStrideMin(Vec,PetscInt,PetscInt *,PetscReal *);
273: PetscPolymorphicFunction(VecStrideMin,(Vec x,PetscInt i),(x,i,PETSC_NULL,&r),PetscReal,r)
274: extern PetscErrorCode  VecStrideScale(Vec,PetscInt,PetscScalar);
275: extern PetscErrorCode  VecStrideSet(Vec,PetscInt,PetscScalar);


278: extern PetscErrorCode  VecStrideGather(Vec,PetscInt,Vec,InsertMode);
279: extern PetscErrorCode  VecStrideScatter(Vec,PetscInt,Vec,InsertMode);
280: extern PetscErrorCode  VecStrideGatherAll(Vec,Vec[],InsertMode);
281: extern PetscErrorCode  VecStrideScatterAll(Vec[],Vec,InsertMode);

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

291: /*MC
292:    VecSetValue - Set a single entry into a vector.

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

297:    Not Collective

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

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

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

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

314:    Level: beginner

316: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal()
317: M*/
318: PETSC_STATIC_INLINE PetscErrorCode VecSetValue(Vec v,PetscInt i,PetscScalar va,InsertMode mode) {return VecSetValues(v,1,&i,&va,mode);}


321: extern PetscErrorCode  VecSetBlockSize(Vec,PetscInt);
322: extern PetscErrorCode  VecGetBlockSize(Vec,PetscInt*);
323: PetscPolymorphicFunction(VecGetBlockSize,(Vec x),(x,&i),PetscInt,i)
324: extern PetscErrorCode  VecSetValuesBlocked(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);

326: /* Dynamic creation and loading functions */
327: extern PetscFList VecList;
328: extern PetscBool  VecRegisterAllCalled;
329: extern PetscErrorCode  VecSetType(Vec, const VecType);
330: extern PetscErrorCode  VecGetType(Vec, const VecType *);
331: extern PetscErrorCode  VecRegister(const char[],const char[],const char[],PetscErrorCode (*)(Vec));
332: extern PetscErrorCode  VecRegisterAll(const char []);
333: extern PetscErrorCode  VecRegisterDestroy(void);

335: /*MC
336:   VecRegisterDynamic - Adds a new vector component implementation

338:   Synopsis:
339:   PetscErrorCode VecRegisterDynamic(const char *name, const char *path, const char *func_name, PetscErrorCode (*create_func)(Vec))

341:   Not Collective

343:   Input Parameters:
344: + name        - The name of a new user-defined creation routine
345: . path        - The path (either absolute or relative) of the library containing this routine
346: . func_name   - The name of routine to create method context
347: - create_func - The creation routine itself

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

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

354:   Sample usage:
355: .vb
356:     VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate);
357: .ve

359:   Then, your vector type can be chosen with the procedural interface via
360: .vb
361:     VecCreate(MPI_Comm, Vec *);
362:     VecSetType(Vec,"my_vector_name");
363: .ve
364:    or at runtime via the option
365: .vb
366:     -vec_type my_vector_name
367: .ve

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

374: .keywords: Vec, register
375: .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister()
376: M*/
377: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
378: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0)
379: #else
380: #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d)
381: #endif


384: extern PetscErrorCode  VecScatterCreate(Vec,IS,Vec,IS,VecScatter *);
385: PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is1,Vec y,IS is2),(x,is1,y,is2,&s),VecScatter,s)
386: PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,IS is,Vec y,VecScatter *s),(x,is,y,PETSC_NULL,s))
387: PetscPolymorphicFunction(VecScatterCreate,(Vec x,IS is,Vec y),(x,is,y,PETSC_NULL,&s),VecScatter,s)
388: PetscPolymorphicSubroutine(VecScatterCreate,(Vec x,Vec y,IS is,VecScatter *s),(x,PETSC_NULL,y,is,s))
389: PetscPolymorphicFunction(VecScatterCreate,(Vec x,Vec y,IS is),(x,PETSC_NULL,y,is,&s),VecScatter,s)
390: extern PetscErrorCode  VecScatterCreateEmpty(MPI_Comm,VecScatter *);
391: extern PetscErrorCode  VecScatterCreateLocal(VecScatter,PetscInt,const PetscInt[],const PetscInt[],const PetscInt[],PetscInt,const PetscInt[],const PetscInt[],const PetscInt[],PetscInt);
392: extern PetscErrorCode  VecScatterBegin(VecScatter,Vec,Vec,InsertMode,ScatterMode);
393: extern PetscErrorCode  VecScatterEnd(VecScatter,Vec,Vec,InsertMode,ScatterMode);
394: extern PetscErrorCode  VecScatterDestroy(VecScatter*);
395: extern PetscErrorCode  VecScatterCopy(VecScatter,VecScatter *);
396: extern PetscErrorCode  VecScatterView(VecScatter,PetscViewer);
397: extern PetscErrorCode  VecScatterRemap(VecScatter,PetscInt *,PetscInt*);
398: extern PetscErrorCode  VecScatterGetMerged(VecScatter,PetscBool *);

400: extern PetscErrorCode  VecGetArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
401: extern PetscErrorCode  VecRestoreArray4d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar****[]);
402: extern PetscErrorCode  VecGetArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
403: extern PetscErrorCode  VecRestoreArray3d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar***[]);
404: extern PetscErrorCode  VecGetArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
405: extern PetscErrorCode  VecRestoreArray2d(Vec,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar**[]);
406: extern PetscErrorCode  VecGetArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);
407: extern PetscErrorCode  VecRestoreArray1d(Vec,PetscInt,PetscInt,PetscScalar *[]);

409: extern PetscErrorCode  VecPlaceArray(Vec,const PetscScalar[]);
410: extern PetscErrorCode  VecResetArray(Vec);
411: extern PetscErrorCode  VecReplaceArray(Vec,const PetscScalar[]);
412: extern PetscErrorCode  VecGetArrays(const Vec[],PetscInt,PetscScalar**[]);
413: extern PetscErrorCode  VecRestoreArrays(const Vec[],PetscInt,PetscScalar**[]);

415: extern PetscErrorCode  VecView(Vec,PetscViewer);
416: extern PetscErrorCode  VecViewFromOptions(Vec, const char *);
417: extern PetscErrorCode  VecEqual(Vec,Vec,PetscBool *);
418: PetscPolymorphicFunction(VecEqual,(Vec x,Vec y),(x,y,&s),PetscBool ,s)
419: extern PetscErrorCode  VecLoad(Vec, PetscViewer);

421: extern PetscErrorCode  VecGetSize(Vec,PetscInt*);
422: PetscPolymorphicFunction(VecGetSize,(Vec x),(x,&s),PetscInt,s)
423: extern PetscErrorCode  VecGetLocalSize(Vec,PetscInt*);
424: PetscPolymorphicFunction(VecGetLocalSize,(Vec x),(x,&s),PetscInt,s)
425: extern PetscErrorCode  VecGetOwnershipRange(Vec,PetscInt*,PetscInt*);
426: extern PetscErrorCode  VecGetOwnershipRanges(Vec,const PetscInt *[]);

428: extern PetscErrorCode  VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping);
429: extern PetscErrorCode  VecSetValuesLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);

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

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

437:    Not Collective

439:    Input Parameters:
440: +  v - the vector
441: .  row - the row location of the entry
442: .  value - the value to insert
443: -  mode - either INSERT_VALUES or ADD_VALUES

445:    Notes:
446:    For efficiency one should use VecSetValues() and set several or 
447:    many values simultaneously if possible.

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

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

454:    Level: beginner

456: .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue()
457: M*/
458: PETSC_STATIC_INLINE PetscErrorCode VecSetValueLocal(Vec v,PetscInt i,PetscScalar va,InsertMode mode) {return VecSetValuesLocal(v,1,&i,&va,mode);}

460: extern PetscErrorCode  VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping);
461: extern PetscErrorCode  VecSetValuesBlockedLocal(Vec,PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
462: extern PetscErrorCode  VecGetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping*);
463: extern PetscErrorCode  VecGetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping*);

465: extern PetscErrorCode  VecDotBegin(Vec,Vec,PetscScalar *);
466: PetscPolymorphicSubroutine(VecDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
467: extern PetscErrorCode  VecDotEnd(Vec,Vec,PetscScalar *);
468: PetscPolymorphicFunction(VecDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
469: extern PetscErrorCode  VecTDotBegin(Vec,Vec,PetscScalar *);
470: PetscPolymorphicSubroutine(VecTDotBegin,(Vec x,Vec y),(x,y,PETSC_NULL))
471: extern PetscErrorCode  VecTDotEnd(Vec,Vec,PetscScalar *);
472: PetscPolymorphicFunction(VecTDotEnd,(Vec x,Vec y),(x,y,&s),PetscScalar,s)
473: extern PetscErrorCode  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  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: extern PetscErrorCode  VecMDotBegin(Vec,PetscInt,const Vec[],PetscScalar[]);
481: extern PetscErrorCode  VecMDotEnd(Vec,PetscInt,const Vec[],PetscScalar[]);
482: extern PetscErrorCode  VecMTDotBegin(Vec,PetscInt,const Vec[],PetscScalar[]);
483: extern PetscErrorCode  VecMTDotEnd(Vec,PetscInt,const Vec[],PetscScalar[]);


486: typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_IGNORE_NEGATIVE_INDICES} VecOption;
487: extern PetscErrorCode  VecSetOption(Vec,VecOption,PetscBool );

489: /*
490:    Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function
491:    call overhead on any 'native' Vecs.
492: */

494:  #include private/vecimpl.h

496: extern PetscErrorCode  VecContourScale(Vec,PetscReal,PetscReal);

498: /*
499:     These numbers need to match the entries in 
500:   the function table in vecimpl.h
501: */
502: typedef enum { VECOP_VIEW = 33, VECOP_LOAD = 41, VECOP_DUPLICATE = 0} VecOperation;
503: extern PetscErrorCode  VecSetOperation(Vec,VecOperation,void(*)(void));

505: /*
506:      Routines for dealing with ghosted vectors:
507:   vectors with ghost elements at the end of the array.
508: */
509: extern PetscErrorCode  VecCreateGhost(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
510: extern PetscErrorCode  VecCreateGhostWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
511: extern PetscErrorCode  VecCreateGhostBlock(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Vec*);
512: extern PetscErrorCode  VecCreateGhostBlockWithArray(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscScalar[],Vec*);
513: extern PetscErrorCode  VecGhostGetLocalForm(Vec,Vec*);
514: PetscPolymorphicFunction(VecGhostGetLocalForm,(Vec x),(x,&s),Vec,s)
515: extern PetscErrorCode  VecGhostRestoreLocalForm(Vec,Vec*);
516: extern PetscErrorCode  VecGhostUpdateBegin(Vec,InsertMode,ScatterMode);
517: extern PetscErrorCode  VecGhostUpdateEnd(Vec,InsertMode,ScatterMode);

519: extern PetscErrorCode  VecConjugate(Vec);

521: extern PetscErrorCode  VecScatterCreateToAll(Vec,VecScatter*,Vec*);
522: extern PetscErrorCode  VecScatterCreateToZero(Vec,VecScatter*,Vec*);

524: extern PetscErrorCode  PetscViewerMathematicaGetVector(PetscViewer, Vec);
525: extern PetscErrorCode  PetscViewerMathematicaPutVector(PetscViewer, Vec);

527: /*S
528:      Vecs - Collection of vectors where the data for the vectors is stored in 
529:             one contiguous memory

531:    Level: advanced

533:    Notes:
534:     Temporary construct for handling multiply right hand side solves

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

539:   Concepts: parallel decomposition

541: S*/
542:         struct _n_Vecs  {PetscInt n; Vec v;};
543: typedef struct _n_Vecs* Vecs;
544: #define VecsDestroy(x)            (VecDestroy(&(x)->v)         || PetscFree(x))
545: #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
546: #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _n_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m))))
547: #define VecsDuplicate(x,y)        (PetscNew(struct _n_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n)))

549: #if defined(PETSC_HAVE_CUSP)
550: typedef struct _p_PetscCUSPIndices* PetscCUSPIndices;
551: extern PetscErrorCode PetscCUSPIndicesCreate(PetscInt,const PetscInt*,PetscCUSPIndices*);
552: extern PetscErrorCode PetscCUSPIndicesDestroy(PetscCUSPIndices*);
553: extern PetscErrorCode VecCUSPCopyToGPUSome_Public(Vec,PetscCUSPIndices);
554: extern PetscErrorCode VecCUSPCopyFromGPUSome_Public(Vec,PetscCUSPIndices);

556: extern PetscErrorCode  VecCreateSeqCUSP(MPI_Comm,PetscInt,Vec*);
557: extern PetscErrorCode  VecCreateMPICUSP(MPI_Comm,PetscInt,PetscInt,Vec*);
558: #endif

560: extern PetscErrorCode  VecNestGetSubVecs(Vec,PetscInt*,Vec**);
561: extern PetscErrorCode  VecNestGetSubVec(Vec,PetscInt,Vec*);
562: extern PetscErrorCode  VecCreateNest(MPI_Comm,PetscInt,IS*,Vec*,Vec*);
563: extern PetscErrorCode  VecNestGetSize(Vec,PetscInt*);

565: PETSC_EXTERN_CXX_END
566: #endif