Actual source code: vector.c
1: /*$Id: vector.c,v 1.238 2001/09/11 16:31:48 bsmith Exp $*/
2: /*
3: Provides the interface functions for all vector operations.
4: These are the vector functions the user calls.
5: */
6: #include src/vec/vecimpl.h
8: /* Logging support */
9: int VEC_COOKIE;
10: int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier;
11: int VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin;
12: int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd;
13: int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication;
17: /*
18: VecSetTypeFromOptions_Private - Sets the type of vector from user options. Defaults to a PETSc sequential vector on one
19: processor and a PETSc MPI vector on more than one processor.
21: Collective on Vec
23: Input Parameter:
24: . vec - The vector
26: Level: intermediate
28: .keywords: Vec, set, options, database, type
29: .seealso: VecSetFromOptions(), VecSetType()
30: */
31: static int VecSetTypeFromOptions_Private(Vec vec)
32: {
33: PetscTruth opt;
34: char *defaultType;
35: char typeName[256];
36: int numProcs;
37: int ierr;
40: if (vec->type_name != PETSC_NULL) {
41: defaultType = vec->type_name;
42: } else {
43: MPI_Comm_size(vec->comm, &numProcs);
44: if (numProcs > 1) {
45: defaultType = VECMPI;
46: } else {
47: defaultType = VECSEQ;
48: }
49: }
51: if (!VecRegisterAllCalled) {
52: VecRegisterAll(PETSC_NULL);
53: }
54: PetscOptionsList("-vec_type", "Vector type"," VecSetType", VecList, defaultType, typeName, 256, &opt);
55:
56: if (opt == PETSC_TRUE) {
57: VecSetType(vec, typeName);
58: } else {
59: VecSetType(vec, defaultType);
60: }
61: return(0);
62: }
66: /*@C
67: VecSetFromOptions - Configures the vector from the options database.
69: Collective on Vec
71: Input Parameter:
72: . vec - The vector
74: Notes: To see all options, run your program with the -help option, or consult the users manual.
75: Must be called after VecCreate() but before the vector is used.
77: Level: beginner
79: Concepts: vectors^setting options
80: Concepts: vectors^setting type
82: .keywords: Vec, set, options, database
83: .seealso: VecCreate(), VecPrintHelp(), VechSetOptionsPrefix()
84: @*/
85: int VecSetFromOptions(Vec vec)
86: {
87: PetscTruth opt;
88: int ierr;
93: PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");
95: /* Handle generic vector options */
96: PetscOptionsHasName(PETSC_NULL, "-help", &opt);
97: if (opt == PETSC_TRUE) {
98: VecPrintHelp(vec);
99: }
101: /* Handle vector type options */
102: VecSetTypeFromOptions_Private(vec);
104: /* Handle specific vector options */
105: if (vec->ops->setfromoptions != PETSC_NULL) {
106: (*vec->ops->setfromoptions)(vec);
107: }
108: PetscOptionsEnd();
110: #if defined(__cplusplus) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE) && defined(PETSC_HAVE_CXX_NAMESPACE)
111: VecESISetFromOptions(vec);
112: #endif
114: VecViewFromOptions(vec, vec->name);
115: return(0);
116: }
120: /*@
121: VecPrintHelp - Prints some options for the Vec.
123: Input Parameter:
124: . vec - The vector
126: Options Database Keys:
127: $ -help, -h
129: Level: intermediate
131: .keywords: Vec, help
132: .seealso: VecSetFromOptions()
133: @*/
134: int VecPrintHelp(Vec vec)
135: {
138: return(0);
139: }
143: /*@
144: VecSetSizes - Sets the local and global sizes, and checks to determine compatibility
146: Collective on Vec
148: Input Parameters:
149: + v - the vector
150: . n - the local size (or PETSC_DECIDE to have it set)
151: - N - the global size (or PETSC_DECIDE)
153: Notes:
154: n and N cannot be both PETSC_DECIDE
155: If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.
157: Level: intermediate
159: .seealso: VecGetSize(), PetscSplitOwnership()
160: @*/
161: int VecSetSizes(Vec v, int n, int N)
162: {
165: v->n = n;
166: v->N = N;
167: return(0);
168: }
172: /*@
173: VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
174: and VecSetValuesBlockedLocal().
176: Collective on Vec
178: Input Parameter:
179: + v - the vector
180: - bs - the blocksize
182: Notes:
183: All vectors obtained by VecDuplicate() inherit the same blocksize.
185: Level: advanced
187: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecGetBlockSize()
189: Concepts: block size^vectors
190: @*/
191: int VecSetBlockSize(Vec v,int bs)
192: {
195: if (bs <= 0) bs = 1;
196: if (bs == v->bs) return(0);
197: if (v->bs != -1) SETERRQ2(PETSC_ERR_ARG_WRONGSTATE,"Cannot reset blocksize. Current size %d new %d",v->bs,bs);
198: if (v->N != -1 && v->N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %d %d",v->N,bs);
199: if (v->n != -1 && v->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %d %d\n\
200: Try setting blocksize before setting the vector type",v->n,bs);
201:
202: v->bs = bs;
203: v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
204: return(0);
205: }
209: /*@
210: VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
211: and VecSetValuesBlockedLocal().
213: Collective on Vec
215: Input Parameter:
216: . v - the vector
218: Output Parameter:
219: . bs - the blocksize
221: Notes:
222: All vectors obtained by VecDuplicate() inherit the same blocksize.
224: Level: advanced
226: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecSetBlockSize()
228: Concepts: vector^block size
229: Concepts: block^vector
231: @*/
232: int VecGetBlockSize(Vec v,int *bs)
233: {
236: *bs = v->bs;
237: return(0);
238: }
242: /*@
243: VecValid - Checks whether a vector object is valid.
245: Not Collective
247: Input Parameter:
248: . v - the object to check
250: Output Parameter:
251: flg - flag indicating vector status, either
252: PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.
254: Level: developer
256: @*/
257: int VecValid(Vec v,PetscTruth *flg)
258: {
261: if (!v) *flg = PETSC_FALSE;
262: else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
263: else *flg = PETSC_TRUE;
264: return(0);
265: }
269: /*@
270: VecDot - Computes the vector dot product.
272: Collective on Vec
274: Input Parameters:
275: . x, y - the vectors
277: Output Parameter:
278: . alpha - the dot product
280: Performance Issues:
281: + per-processor memory bandwidth
282: . interprocessor latency
283: - work load inbalance that causes certain processes to arrive much earlier than
284: others
286: Notes for Users of Complex Numbers:
287: For complex vectors, VecDot() computes
288: $ val = (x,y) = y^H x,
289: where y^H denotes the conjugate transpose of y.
291: Use VecTDot() for the indefinite form
292: $ val = (x,y) = y^T x,
293: where y^T denotes the transpose of y.
295: Level: intermediate
297: Concepts: inner product
298: Concepts: vector^inner product
300: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
301: @*/
302: int VecDot(Vec x,Vec y,PetscScalar *val)
303: {
314: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
315: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
317: PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
318: (*x->ops->dot)(x,y,val);
319: PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
320: /*
321: The next block is for incremental debugging
322: */
323: if (PetscCompare) {
324: int flag;
325: MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
326: if (flag != MPI_UNEQUAL) {
327: PetscCompareScalar(*val);
328: }
329: }
330: return(0);
331: }
335: /*@
336: VecNorm - Computes the vector norm.
338: Collective on Vec
340: Input Parameters:
341: + x - the vector
342: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
343: NORM_1_AND_2, which computes both norms and stores them
344: in a two element array.
346: Output Parameter:
347: . val - the norm
349: Notes:
350: $ NORM_1 denotes sum_i |x_i|
351: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
352: $ NORM_INFINITY denotes max_i |x_i|
354: Level: intermediate
356: Performance Issues:
357: + per-processor memory bandwidth
358: . interprocessor latency
359: - work load inbalance that causes certain processes to arrive much earlier than
360: others
362: Compile Option:
363: PETSC_HAVE_SLOW_NRM2 will cause a C (loop unrolled) version of the norm to be used, rather
364: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
365: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
367: Concepts: norm
368: Concepts: vector^norm
370: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(),
371: VecNormBegin(), VecNormEnd()
373: @*/
374: int VecNorm(Vec x,NormType type,PetscReal *val)
375: {
381: if ((type == NORM_2) && (x->normvalid)) {
382: *val = x->normcurrent;
383: return(0);
384: }
385: else {
386: PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
387: (*x->ops->norm)(x,type,val);
388: PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);
389: }
390: /*
391: The next block is for incremental debugging
392: */
393: if (PetscCompare) {
394: int flag;
395: MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
396: if (flag != MPI_UNEQUAL) {
397: PetscCompareDouble(*val);
398: }
399: }
400: if (type == NORM_2) {
401: x->normcurrent = *val;
402: x->normvalid = PETSC_TRUE;
403: }
404: return(0);
405: }
409: /*@
410: VecNormalize - Normalizes a vector by 2-norm.
412: Collective on Vec
414: Input Parameters:
415: + x - the vector
417: Output Parameter:
418: . x - the normalized vector
419: - val - the vector norm before normalization
421: Level: intermediate
423: Concepts: vector^normalizing
424: Concepts: normalizing^vector
426: @*/
427: int VecNormalize (Vec x,PetscReal *val)
428: {
435: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
436: VecNorm(x,NORM_2,val);
437: if (*val == 0.0) {
438: PetscLogInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm");
439: } else {
440: PetscScalar tmp = 1.0/(*val);
441: VecScale(&tmp,x);
442: x->normcurrent = 1.0;
443: x->normvalid = PETSC_TRUE;
444: }
445: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
446: return(0);
447: }
451: /*@C
452: VecMax - Determines the maximum vector component and its location.
454: Collective on Vec
456: Input Parameter:
457: . x - the vector
459: Output Parameters:
460: + val - the maximum component
461: - p - the location of val
463: Notes:
464: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
466: Level: intermediate
468: Concepts: maximum^of vector
469: Concepts: vector^maximum value
471: .seealso: VecNorm(), VecMin()
472: @*/
473: int VecMax(Vec x,int *p,PetscReal *val)
474: {
481: PetscLogEventBegin(VEC_Max,x,0,0,0);
482: (*x->ops->max)(x,p,val);
483: PetscLogEventEnd(VEC_Max,x,0,0,0);
484: return(0);
485: }
489: /*@
490: VecMin - Determines the minimum vector component and its location.
492: Collective on Vec
494: Input Parameters:
495: . x - the vector
497: Output Parameter:
498: + val - the minimum component
499: - p - the location of val
501: Level: intermediate
503: Notes:
504: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
506: Concepts: minimum^of vector
507: Concepts: vector^minimum entry
509: .seealso: VecMax()
510: @*/
511: int VecMin(Vec x,int *p,PetscReal *val)
512: {
519: PetscLogEventBegin(VEC_Min,x,0,0,0);
520: (*x->ops->min)(x,p,val);
521: PetscLogEventEnd(VEC_Min,x,0,0,0);
522: return(0);
523: }
527: /*@
528: VecTDot - Computes an indefinite vector dot product. That is, this
529: routine does NOT use the complex conjugate.
531: Collective on Vec
533: Input Parameters:
534: . x, y - the vectors
536: Output Parameter:
537: . val - the dot product
539: Notes for Users of Complex Numbers:
540: For complex vectors, VecTDot() computes the indefinite form
541: $ val = (x,y) = y^T x,
542: where y^T denotes the transpose of y.
544: Use VecDot() for the inner product
545: $ val = (x,y) = y^H x,
546: where y^H denotes the conjugate transpose of y.
548: Level: intermediate
550: Concepts: inner product^non-Hermitian
551: Concepts: vector^inner product
552: Concepts: non-Hermitian inner product
554: .seealso: VecDot(), VecMTDot()
555: @*/
556: int VecTDot(Vec x,Vec y,PetscScalar *val)
557: {
568: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
569: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
571: PetscLogEventBegin(VEC_TDot,x,y,0,0);
572: (*x->ops->tdot)(x,y,val);
573: PetscLogEventEnd(VEC_TDot,x,y,0,0);
574: return(0);
575: }
579: /*@
580: VecScale - Scales a vector.
582: Collective on Vec
584: Input Parameters:
585: + x - the vector
586: - alpha - the scalar
588: Output Parameter:
589: . x - the scaled vector
591: Note:
592: For a vector with n components, VecScale() computes
593: $ x[i] = alpha * x[i], for i=1,...,n.
595: Level: intermediate
597: Concepts: vector^scaling
598: Concepts: scaling^vector
600: @*/
601: int VecScale (const PetscScalar *alpha,Vec x)
602: {
609: PetscLogEventBegin(VEC_Scale,x,0,0,0);
610: (*x->ops->scale)(alpha,x);
611: PetscLogEventEnd(VEC_Scale,x,0,0,0);
612: /*x->normvalid = PETSC_FALSE;*/
613: if (x->normvalid) x->normcurrent = PetscAbsScalar(*alpha)*x->normcurrent;
614: return(0);
615: }
619: /*@
620: VecCopy - Copies a vector.
622: Collective on Vec
624: Input Parameter:
625: . x - the vector
627: Output Parameter:
628: . y - the copy
630: Notes:
631: For default parallel PETSc vectors, both x and y must be distributed in
632: the same manner; local copies are done.
634: Level: beginner
636: .seealso: VecDuplicate()
637: @*/
638: int VecCopy(Vec x,Vec y)
639: {
648: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
649: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
651: PetscLogEventBegin(VEC_Copy,x,y,0,0);
652: (*x->ops->copy)(x,y);
653: PetscLogEventEnd(VEC_Copy,x,y,0,0);
654: y->normvalid = x->normvalid;
655: y->normcurrent = x->normcurrent;
656: return(0);
657: }
661: /*@
662: VecSet - Sets all components of a vector to a single scalar value.
664: Collective on Vec
666: Input Parameters:
667: + alpha - the scalar
668: - x - the vector
670: Output Parameter:
671: . x - the vector
673: Note:
674: For a vector of dimension n, VecSet() computes
675: $ x[i] = alpha, for i=1,...,n,
676: so that all vector entries then equal the identical
677: scalar value, alpha. Use the more general routine
678: VecSetValues() to set different vector entries.
680: Level: beginner
682: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
684: Concepts: vector^setting to constant
686: @*/
687: int VecSet(const PetscScalar *alpha,Vec x)
688: {
695: x->normvalid = PETSC_FALSE;
697: PetscLogEventBegin(VEC_Set,x,0,0,0);
698: (*x->ops->set)(alpha,x);
699: PetscLogEventEnd(VEC_Set,x,0,0,0);
700: return(0);
701: }
705: /*@C
706: VecSetRandom - Sets all components of a vector to random numbers.
708: Collective on Vec
710: Input Parameters:
711: + rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
712: it will create one internally.
713: - x - the vector
715: Output Parameter:
716: . x - the vector
718: Example of Usage:
719: .vb
720: PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
721: VecSetRandom(rctx,x);
722: PetscRandomDestroy(rctx);
723: .ve
725: Level: intermediate
727: Concepts: vector^setting to random
728: Concepts: random^vector
730: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
731: @*/
732: int VecSetRandom(PetscRandom rctx,Vec x)
733: {
734: int ierr;
735: PetscRandom randObj = PETSC_NULL;
741: x->normvalid = PETSC_FALSE;
743: if (!rctx) {
744: MPI_Comm comm;
745: PetscObjectGetComm((PetscObject)x,&comm);
746: PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
747: rctx = randObj;
748: }
750: PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
751: (*x->ops->setrandom)(rctx,x);
752: PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
753:
754: if (randObj) {
755: PetscRandomDestroy(randObj);
756: }
757: return(0);
758: }
762: /*@
763: VecAXPY - Computes y = alpha x + y.
765: Collective on Vec
767: Input Parameters:
768: + alpha - the scalar
769: - x, y - the vectors
771: Output Parameter:
772: . y - output vector
774: Level: intermediate
776: Concepts: vector^BLAS
777: Concepts: BLAS
779: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
780: @*/
781: int VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
782: {
793: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
794: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
795: y->normvalid = PETSC_FALSE;
797: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
798: (*x->ops->axpy)(alpha,x,y);
799: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
800: return(0);
801: }
805: /*@
806: VecAXPBY - Computes y = alpha x + beta y.
808: Collective on Vec
810: Input Parameters:
811: + alpha,beta - the scalars
812: - x, y - the vectors
814: Output Parameter:
815: . y - output vector
817: Level: intermediate
819: Concepts: BLAS
820: Concepts: vector^BLAS
822: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
823: @*/
824: int VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
825: {
837: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
838: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
839: y->normvalid = PETSC_FALSE;
841: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
842: (*x->ops->axpby)(alpha,beta,x,y);
843: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
844: return(0);
845: }
849: /*@
850: VecAYPX - Computes y = x + alpha y.
852: Collective on Vec
854: Input Parameters:
855: + alpha - the scalar
856: - x, y - the vectors
858: Output Parameter:
859: . y - output vector
861: Level: intermediate
863: Concepts: vector^BLAS
864: Concepts: BLAS
866: .seealso: VecAXPY(), VecWAXPY()
867: @*/
868: int VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
869: {
880: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
881: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
882: y->normvalid = PETSC_FALSE;
884: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
885: (*x->ops->aypx)(alpha,x,y);
886: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
887: return(0);
888: }
892: /*@
893: VecSwap - Swaps the vectors x and y.
895: Collective on Vec
897: Input Parameters:
898: . x, y - the vectors
900: Level: advanced
902: Concepts: vector^swapping values
904: @*/
905: int VecSwap(Vec x,Vec y)
906: {
916: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
917: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
919: PetscLogEventBegin(VEC_Swap,x,y,0,0);
920: (*x->ops->swap)(x,y);
921: PetscLogEventEnd(VEC_Swap,x,y,0,0);
922: {
923: PetscTruth normvalid = x->normvalid;
924: PetscReal normcurrent = x->normcurrent;
925:
926: x->normvalid = y->normvalid;
927: x->normcurrent = y->normcurrent;
928: y->normvalid = normvalid;
929: y->normcurrent = normcurrent;
930: }
931: return(0);
932: }
936: /*@
937: VecWAXPY - Computes w = alpha x + y.
939: Collective on Vec
941: Input Parameters:
942: + alpha - the scalar
943: - x, y - the vectors
945: Output Parameter:
946: . w - the result
948: Level: intermediate
950: Concepts: vector^BLAS
951: Concepts: BLAS
953: .seealso: VecAXPY(), VecAYPX()
954: @*/
955: int VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
956: {
969: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
970: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
971: w->normvalid = PETSC_FALSE;
973: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
974: (*x->ops->waxpy)(alpha,x,y,w);
975: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
976: return(0);
977: }
981: /*@
982: VecPointwiseMult - Computes the componentwise multiplication w = x*y.
984: Collective on Vec
986: Input Parameters:
987: . x, y - the vectors
989: Output Parameter:
990: . w - the result
992: Level: advanced
994: Notes: any subset of the x, y, and w may be the same vector.
996: Concepts: vector^pointwise multiply
998: .seealso: VecPointwiseDivide()
999: @*/
1000: int VecPointwiseMult(Vec x,Vec y,Vec w)
1001: {
1013: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1014: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1015: w->normvalid = PETSC_FALSE;
1017: PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1018: (*x->ops->pointwisemult)(x,y,w);
1019: PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1020: return(0);
1021: }
1025: /*@
1026: VecPointwiseDivide - Computes the componentwise division w = x/y.
1028: Collective on Vec
1030: Input Parameters:
1031: . x, y - the vectors
1033: Output Parameter:
1034: . w - the result
1036: Level: advanced
1038: Notes: any subset of the x, y, and w may be the same vector.
1040: Concepts: vector^pointwise divide
1042: .seealso: VecPointwiseMult()
1043: @*/
1044: int VecPointwiseDivide(Vec x,Vec y,Vec w)
1045: {
1057: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1058: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1059: w->normvalid = PETSC_FALSE;
1061: (*x->ops->pointwisedivide)(x,y,w);
1062: return(0);
1063: }
1067: /*@
1068: VecMaxPointwiseDivide - Computes the maximum of the componentwise division w = abs(x/y).
1070: Collective on Vec
1072: Input Parameters:
1073: . x, y - the vectors
1075: Output Parameter:
1076: . max - the result
1078: Level: advanced
1080: Notes: any subset of the x, y, and w may be the same vector.
1082: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1083: @*/
1084: int VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1085: {
1095: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1096: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1098: (*x->ops->maxpointwisedivide)(x,y,max);
1099: return(0);
1100: }
1104: /*@C
1105: VecDuplicate - Creates a new vector of the same type as an existing vector.
1107: Collective on Vec
1109: Input Parameters:
1110: . v - a vector to mimic
1112: Output Parameter:
1113: . newv - location to put new vector
1115: Notes:
1116: VecDuplicate() does not copy the vector, but rather allocates storage
1117: for the new vector. Use VecCopy() to copy a vector.
1119: Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1120: vectors.
1122: Level: beginner
1124: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1125: @*/
1126: int VecDuplicate(Vec x,Vec *newv)
1127: {
1134: (*x->ops->duplicate)(x,newv);
1135: return(0);
1136: }
1140: /*@C
1141: VecDestroy - Destroys a vector.
1143: Collective on Vec
1145: Input Parameters:
1146: . v - the vector
1148: Level: beginner
1150: .seealso: VecDuplicate(), VecDestroyVecs()
1151: @*/
1152: int VecDestroy(Vec v)
1153: {
1158: if (--v->refct > 0) return(0);
1159: /* destroy the internal part */
1160: if (v->ops->destroy) {
1161: (*v->ops->destroy)(v);
1162: }
1163: /* destroy the external/common part */
1164: if (v->mapping) {
1165: ISLocalToGlobalMappingDestroy(v->mapping);
1166: }
1167: if (v->bmapping) {
1168: ISLocalToGlobalMappingDestroy(v->bmapping);
1169: }
1170: if (v->map) {
1171: PetscMapDestroy(v->map);
1172: }
1173: PetscLogObjectDestroy(v);
1174: PetscHeaderDestroy(v);
1175: return(0);
1176: }
1180: /*@C
1181: VecDuplicateVecs - Creates several vectors of the same type as an existing vector.
1183: Collective on Vec
1185: Input Parameters:
1186: + m - the number of vectors to obtain
1187: - v - a vector to mimic
1189: Output Parameter:
1190: . V - location to put pointer to array of vectors
1192: Notes:
1193: Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1194: vector.
1196: Fortran Note:
1197: The Fortran interface is slightly different from that given below, it
1198: requires one to pass in V a Vec (integer) array of size at least m.
1199: See the Fortran chapter of the users manual and petsc/src/vec/examples for details.
1201: Level: intermediate
1203: .seealso: VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1204: @*/
1205: int VecDuplicateVecs(Vec v,int m,Vec *V[])
1206: {
1213: (*v->ops->duplicatevecs)(v, m,V);
1214: return(0);
1215: }
1219: /*@C
1220: VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().
1222: Collective on Vec
1224: Input Parameters:
1225: + vv - pointer to array of vector pointers
1226: - m - the number of vectors previously obtained
1228: Fortran Note:
1229: The Fortran interface is slightly different from that given below.
1230: See the Fortran chapter of the users manual and
1231: petsc/src/vec/examples for details.
1233: Level: intermediate
1235: .seealso: VecDuplicateVecs(), VecDestroyVecsF90()
1236: @*/
1237: int VecDestroyVecs(const Vec vv[],int m)
1238: {
1242: if (!vv) SETERRQ(PETSC_ERR_ARG_BADPTR,"Null vectors");
1245: (*(*vv)->ops->destroyvecs)(vv,m);
1246: return(0);
1247: }
1251: /*@
1252: VecSetValues - Inserts or adds values into certain locations of a vector.
1254: Input Parameters:
1255: Not Collective
1257: + x - vector to insert in
1258: . ni - number of elements to add
1259: . ix - indices where to add
1260: . y - array of values
1261: - iora - either INSERT_VALUES or ADD_VALUES, where
1262: ADD_VALUES adds values to any existing entries, and
1263: INSERT_VALUES replaces existing entries with new values
1265: Notes:
1266: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1268: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1269: options cannot be mixed without intervening calls to the assembly
1270: routines.
1272: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1273: MUST be called after all calls to VecSetValues() have been completed.
1275: VecSetValues() uses 0-based indices in Fortran as well as in C.
1277: Negative indices may be passed in ix, these rows are
1278: simply ignored. This allows easily inserting element load matrices
1279: with homogeneous Dirchlet boundary conditions that you don't want represented
1280: in the vector.
1282: Level: beginner
1284: Concepts: vector^setting values
1286: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1287: VecSetValue(), VecSetValuesBlocked()
1288: @*/
1289: int VecSetValues(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1290: {
1298: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1299: (*x->ops->setvalues)(x,ni,ix,y,iora);
1300: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1301: x->normvalid = PETSC_FALSE;
1302: return(0);
1303: }
1307: /*@
1308: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
1310: Not Collective
1312: Input Parameters:
1313: + x - vector to insert in
1314: . ni - number of blocks to add
1315: . ix - indices where to add in block count, rather than element count
1316: . y - array of values
1317: - iora - either INSERT_VALUES or ADD_VALUES, where
1318: ADD_VALUES adds values to any existing entries, and
1319: INSERT_VALUES replaces existing entries with new values
1321: Notes:
1322: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
1323: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
1325: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1326: options cannot be mixed without intervening calls to the assembly
1327: routines.
1329: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1330: MUST be called after all calls to VecSetValuesBlocked() have been completed.
1332: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
1334: Negative indices may be passed in ix, these rows are
1335: simply ignored. This allows easily inserting element load matrices
1336: with homogeneous Dirchlet boundary conditions that you don't want represented
1337: in the vector.
1339: Level: intermediate
1341: Concepts: vector^setting values blocked
1343: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1344: VecSetValues()
1345: @*/
1346: int VecSetValuesBlocked(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1347: {
1355: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1356: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1357: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1358: x->normvalid = PETSC_FALSE;
1359: return(0);
1360: }
1364: /*@
1365: VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1366: by the routine VecSetValuesLocal() to allow users to insert vector entries
1367: using a local (per-processor) numbering.
1369: Collective on Vec
1371: Input Parameters:
1372: + x - vector
1373: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1375: Notes:
1376: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1378: Level: intermediate
1380: Concepts: vector^setting values with local numbering
1382: seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1383: VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1384: @*/
1385: int VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1386: {
1392: if (x->mapping) {
1393: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1394: }
1396: if (x->ops->setlocaltoglobalmapping) {
1397: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1398: } else {
1399: x->mapping = mapping;
1400: PetscObjectReference((PetscObject)mapping);
1401: }
1402: return(0);
1403: }
1407: /*@
1408: VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1409: by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1410: using a local (per-processor) numbering.
1412: Collective on Vec
1414: Input Parameters:
1415: + x - vector
1416: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1418: Notes:
1419: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1421: Level: intermediate
1423: Concepts: vector^setting values blocked with local numbering
1425: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1426: VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1427: @*/
1428: int VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1429: {
1435: if (x->bmapping) {
1436: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1437: }
1438: x->bmapping = mapping;
1439: PetscObjectReference((PetscObject)mapping);
1440: return(0);
1441: }
1445: /*@
1446: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1447: using a local ordering of the nodes.
1449: Not Collective
1451: Input Parameters:
1452: + x - vector to insert in
1453: . ni - number of elements to add
1454: . ix - indices where to add
1455: . y - array of values
1456: - iora - either INSERT_VALUES or ADD_VALUES, where
1457: ADD_VALUES adds values to any existing entries, and
1458: INSERT_VALUES replaces existing entries with new values
1460: Level: intermediate
1462: Notes:
1463: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1465: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1466: options cannot be mixed without intervening calls to the assembly
1467: routines.
1469: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1470: MUST be called after all calls to VecSetValuesLocal() have been completed.
1472: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
1474: Concepts: vector^setting values with local numbering
1476: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1477: VecSetValuesBlockedLocal()
1478: @*/
1479: int VecSetValuesLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1480: {
1481: int ierr,lixp[128],*lix = lixp;
1489: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1490: if (!x->ops->setvalueslocal) {
1491: if (!x->mapping) {
1492: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1493: }
1494: if (ni > 128) {
1495: PetscMalloc(ni*sizeof(int),&lix);
1496: }
1497: ISLocalToGlobalMappingApply(x->mapping,ni,(int*)ix,lix);
1498: (*x->ops->setvalues)(x,ni,lix,y,iora);
1499: if (ni > 128) {
1500: PetscFree(lix);
1501: }
1502: } else {
1503: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1504: }
1505: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1506: x->normvalid = PETSC_FALSE;
1507: return(0);
1508: }
1512: /*@
1513: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1514: using a local ordering of the nodes.
1516: Not Collective
1518: Input Parameters:
1519: + x - vector to insert in
1520: . ni - number of blocks to add
1521: . ix - indices where to add in block count, not element count
1522: . y - array of values
1523: - iora - either INSERT_VALUES or ADD_VALUES, where
1524: ADD_VALUES adds values to any existing entries, and
1525: INSERT_VALUES replaces existing entries with new values
1527: Level: intermediate
1529: Notes:
1530: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
1531: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
1533: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1534: options cannot be mixed without intervening calls to the assembly
1535: routines.
1537: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1538: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
1540: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
1543: Concepts: vector^setting values blocked with local numbering
1545: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
1546: VecSetLocalToGlobalMappingBlocked()
1547: @*/
1548: int VecSetValuesBlockedLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1549: {
1550: int ierr,lixp[128],*lix = lixp;
1557: if (!x->bmapping) {
1558: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1559: }
1560: if (ni > 128) {
1561: PetscMalloc(ni*sizeof(int),&lix);
1562: }
1564: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1565: ISLocalToGlobalMappingApply(x->bmapping,ni,(int*)ix,lix);
1566: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1567: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1568: if (ni > 128) {
1569: PetscFree(lix);
1570: }
1571: x->normvalid = PETSC_FALSE;
1572: return(0);
1573: }
1577: /*@
1578: VecAssemblyBegin - Begins assembling the vector. This routine should
1579: be called after completing all calls to VecSetValues().
1581: Collective on Vec
1583: Input Parameter:
1584: . vec - the vector
1586: Level: beginner
1588: Concepts: assembly^vectors
1590: .seealso: VecAssemblyEnd(), VecSetValues()
1591: @*/
1592: int VecAssemblyBegin(Vec vec)
1593: {
1594: int ierr;
1595: PetscTruth flg;
1601: PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1602: if (flg) {
1603: VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1604: }
1606: PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1607: if (vec->ops->assemblybegin) {
1608: (*vec->ops->assemblybegin)(vec);
1609: }
1610: PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1611: return(0);
1612: }
1616: /*@
1617: VecAssemblyEnd - Completes assembling the vector. This routine should
1618: be called after VecAssemblyBegin().
1620: Collective on Vec
1622: Input Parameter:
1623: . vec - the vector
1625: Options Database Keys:
1626: . -vec_view - Prints vector in ASCII format
1627: . -vec_view_matlab - Prints vector in Matlab format
1628: . -vec_view_draw - Activates vector viewing using drawing tools
1629: . -display <name> - Sets display name (default is host)
1630: . -draw_pause <sec> - Sets number of seconds to pause after display
1631: . -vec_view_socket - Activates vector viewing using a socket
1632: - -vec_view_ams - Activates vector viewing using the ALICE Memory Snooper (AMS)
1633:
1634: Level: beginner
1636: .seealso: VecAssemblyBegin(), VecSetValues()
1637: @*/
1638: int VecAssemblyEnd(Vec vec)
1639: {
1640: int ierr;
1641: PetscTruth flg;
1645: PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
1647: if (vec->ops->assemblyend) {
1648: (*vec->ops->assemblyend)(vec);
1649: }
1650: PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
1651: PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
1652: PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
1653: if (flg) {
1654: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1655: }
1656: PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
1657: if (flg) {
1658: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
1659: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1660: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
1661: }
1662: PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
1663: if (flg) {
1664: VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
1665: PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
1666: }
1667: PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
1668: if (flg) {
1669: VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
1670: PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
1671: }
1672: #if defined(PETSC_HAVE_AMS)
1673: PetscOptionsName("-vec_view_ams","View vector using AMS","VecView",&flg);
1674: if (flg) {
1675: VecView(vec,PETSC_VIEWER_AMS_(vec->comm));
1676: }
1677: #endif
1678: PetscOptionsEnd();
1679: /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
1680: /* hence they should not be inside the above PetscOptionsBegin/End block. */
1681: PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
1682: if (flg) {
1683: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1684: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1685: }
1686: PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
1687: if (flg) {
1688: PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
1689: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1690: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1691: }
1692: vec->normvalid = PETSC_FALSE;
1693: return(0);
1694: }
1699: /*@C
1700: VecMTDot - Computes indefinite vector multiple dot products.
1701: That is, it does NOT use the complex conjugate.
1703: Collective on Vec
1705: Input Parameters:
1706: + nv - number of vectors
1707: . x - one vector
1708: - y - array of vectors. Note that vectors are pointers
1710: Output Parameter:
1711: . val - array of the dot products
1713: Notes for Users of Complex Numbers:
1714: For complex vectors, VecMTDot() computes the indefinite form
1715: $ val = (x,y) = y^T x,
1716: where y^T denotes the transpose of y.
1718: Use VecMDot() for the inner product
1719: $ val = (x,y) = y^H x,
1720: where y^H denotes the conjugate transpose of y.
1722: Level: intermediate
1724: Concepts: inner product^multiple
1725: Concepts: vector^multiple inner products
1727: .seealso: VecMDot(), VecTDot()
1728: @*/
1729: int VecMTDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1730: {
1741: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1742: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1744: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1745: (*x->ops->mtdot)(nv,x,y,val);
1746: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1747: return(0);
1748: }
1752: /*@C
1753: VecMDot - Computes vector multiple dot products.
1755: Collective on Vec
1757: Input Parameters:
1758: + nv - number of vectors
1759: . x - one vector
1760: - y - array of vectors.
1762: Output Parameter:
1763: . val - array of the dot products
1765: Notes for Users of Complex Numbers:
1766: For complex vectors, VecMDot() computes
1767: $ val = (x,y) = y^H x,
1768: where y^H denotes the conjugate transpose of y.
1770: Use VecMTDot() for the indefinite form
1771: $ val = (x,y) = y^T x,
1772: where y^T denotes the transpose of y.
1774: Level: intermediate
1776: Concepts: inner product^multiple
1777: Concepts: vector^multiple inner products
1779: .seealso: VecMTDot(), VecDot()
1780: @*/
1781: int VecMDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1782: {
1793: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1794: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1796: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1797: (*x->ops->mdot)(nv,x,y,val);
1798: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
1799: return(0);
1800: }
1804: /*@C
1805: VecMAXPY - Computes y = y + sum alpha[j] x[j]
1807: Collective on Vec
1809: Input Parameters:
1810: + nv - number of scalars and x-vectors
1811: . alpha - array of scalars
1812: . y - one vector
1813: - x - array of vectors
1815: Level: intermediate
1817: Concepts: BLAS
1819: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1820: @*/
1821: int VecMAXPY(int nv,const PetscScalar *alpha,Vec y,Vec *x)
1822: {
1833: if (y->N != (*x)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1834: if (y->n != (*x)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1836: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1837: (*y->ops->maxpy)(nv,alpha,y,x);
1838: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1839: y->normvalid = PETSC_FALSE;
1840: return(0);
1841: }
1845: /*@C
1846: VecGetArray - Returns a pointer to a contiguous array that contains this
1847: processor's portion of the vector data. For the standard PETSc
1848: vectors, VecGetArray() returns a pointer to the local data array and
1849: does not use any copies. If the underlying vector data is not stored
1850: in a contiquous array this routine will copy the data to a contiquous
1851: array and return a pointer to that. You MUST call VecRestoreArray()
1852: when you no longer need access to the array.
1854: Not Collective
1856: Input Parameter:
1857: . x - the vector
1859: Output Parameter:
1860: . a - location to put pointer to the array
1862: Fortran Note:
1863: This routine is used differently from Fortran 77
1864: $ Vec x
1865: $ PetscScalar x_array(1)
1866: $ PetscOffset i_x
1867: $ int ierr
1868: $ call VecGetArray(x,x_array,i_x,ierr)
1869: $
1870: $ Access first local entry in vector with
1871: $ value = x_array(i_x + 1)
1872: $
1873: $ ...... other code
1874: $ call VecRestoreArray(x,x_array,i_x,ierr)
1875: For Fortran 90 see VecGetArrayF90()
1877: See the Fortran chapter of the users manual and
1878: petsc/src/snes/examples/tutorials/ex5f.F for details.
1880: Level: beginner
1882: Concepts: vector^accessing local values
1884: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1885: @*/
1886: int VecGetArray(Vec x,PetscScalar *a[])
1887: {
1894: (*x->ops->getarray)(x,a);
1895: return(0);
1896: }
1901: /*@C
1902: VecGetArrays - Returns a pointer to the arrays in a set of vectors
1903: that were created by a call to VecDuplicateVecs(). You MUST call
1904: VecRestoreArrays() when you no longer need access to the array.
1906: Not Collective
1908: Input Parameter:
1909: + x - the vectors
1910: - n - the number of vectors
1912: Output Parameter:
1913: . a - location to put pointer to the array
1915: Fortran Note:
1916: This routine is not supported in Fortran.
1918: Level: intermediate
1920: .seealso: VecGetArray(), VecRestoreArrays()
1921: @*/
1922: int VecGetArrays(const Vec x[],int n,PetscScalar **a[])
1923: {
1924: int i,ierr;
1925: PetscScalar **q;
1930: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %d",n);
1931: PetscMalloc(n*sizeof(PetscScalar*),&q);
1932: for (i=0; i<n; ++i) {
1933: VecGetArray(x[i],&q[i]);
1934: }
1935: *a = q;
1936: return(0);
1937: }
1941: /*@C
1942: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1943: has been called.
1945: Not Collective
1947: Input Parameters:
1948: + x - the vector
1949: . n - the number of vectors
1950: - a - location of pointer to arrays obtained from VecGetArrays()
1952: Notes:
1953: For regular PETSc vectors this routine does not involve any copies. For
1954: any special vectors that do not store local vector data in a contiguous
1955: array, this routine will copy the data back into the underlying
1956: vector data structure from the arrays obtained with VecGetArrays().
1958: Fortran Note:
1959: This routine is not supported in Fortran.
1961: Level: intermediate
1963: .seealso: VecGetArrays(), VecRestoreArray()
1964: @*/
1965: int VecRestoreArrays(const Vec x[],int n,PetscScalar **a[])
1966: {
1967: int i,ierr;
1968: PetscScalar **q = *a;
1974: for(i=0;i<n;++i) {
1975: VecRestoreArray(x[i],&q[i]);
1976: x[i]->normvalid = PETSC_FALSE;
1977: }
1978: PetscFree(q);
1979: return(0);
1980: }
1984: /*@C
1985: VecRestoreArray - Restores a vector after VecGetArray() has been called.
1987: Not Collective
1989: Input Parameters:
1990: + x - the vector
1991: - a - location of pointer to array obtained from VecGetArray()
1993: Level: beginner
1995: Notes:
1996: For regular PETSc vectors this routine does not involve any copies. For
1997: any special vectors that do not store local vector data in a contiguous
1998: array, this routine will copy the data back into the underlying
1999: vector data structure from the array obtained with VecGetArray().
2001: This routine actually zeros out the a pointer. This is to prevent accidental
2002: us of the array after it has been restored. If you pass null for a it will
2003: not zero the array pointer a.
2005: Fortran Note:
2006: This routine is used differently from Fortran 77
2007: $ Vec x
2008: $ PetscScalar x_array(1)
2009: $ PetscOffset i_x
2010: $ int ierr
2011: $ call VecGetArray(x,x_array,i_x,ierr)
2012: $
2013: $ Access first local entry in vector with
2014: $ value = x_array(i_x + 1)
2015: $
2016: $ ...... other code
2017: $ call VecRestoreArray(x,x_array,i_x,ierr)
2019: See the Fortran chapter of the users manual and
2020: petsc/src/snes/examples/tutorials/ex5f.F for details.
2021: For Fortran 90 see VecRestoreArrayF90()
2023: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2024: @*/
2025: int VecRestoreArray(Vec x,PetscScalar *a[])
2026: {
2033: #if defined(PETSC_USE_BOPT_g)
2034: CHKMEMQ;
2035: #endif
2036: if (x->ops->restorearray) {
2037: (*x->ops->restorearray)(x,a);
2038: }
2039: x->normvalid = PETSC_FALSE;
2040: return(0);
2041: }
2043: #undef __FUNCT__
2045: /*@
2046: VecViewFromOptions - This function visualizes the vector based upon user options.
2048: Collective on Vec
2050: Input Parameters:
2051: . vec - The vector
2052: . title - The title
2054: Level: intermediate
2056: .keywords: Vec, view, options, database
2057: .seealso: VecSetFromOptions(), VecView()
2058: @*/
2059: int VecViewFromOptions(Vec vec, char *title)
2060: {
2061: PetscViewer viewer;
2062: PetscDraw draw;
2063: PetscTruth opt;
2064: char *titleStr;
2065: char typeName[1024];
2066: char fileName[PETSC_MAX_PATH_LEN];
2067: int len;
2068: int ierr;
2071: PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2072: if (opt == PETSC_TRUE) {
2073: PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2074: PetscStrlen(typeName, &len);
2075: if (len > 0) {
2076: PetscViewerCreate(vec->comm, &viewer);
2077: PetscViewerSetType(viewer, typeName);
2078: PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2079: if (opt == PETSC_TRUE) {
2080: PetscViewerSetFilename(viewer, fileName);
2081: } else {
2082: PetscViewerSetFilename(viewer, vec->name);
2083: }
2084: VecView(vec, viewer);
2085: PetscViewerFlush(viewer);
2086: PetscViewerDestroy(viewer);
2087: } else {
2088: VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2089: }
2090: }
2091: PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2092: if (opt == PETSC_TRUE) {
2093: PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2094: PetscViewerDrawGetDraw(viewer, 0, &draw);
2095: if (title != PETSC_NULL) {
2096: titleStr = title;
2097: } else {
2098: PetscObjectName((PetscObject) vec); CHKERRQ(ierr) ;
2099: titleStr = vec->name;
2100: }
2101: PetscDrawSetTitle(draw, titleStr);
2102: VecView(vec, viewer);
2103: PetscViewerFlush(viewer);
2104: PetscDrawPause(draw);
2105: PetscViewerDestroy(viewer);
2106: }
2107: return(0);
2108: }
2112: /*@C
2113: VecView - Views a vector object.
2115: Collective on Vec
2117: Input Parameters:
2118: + v - the vector
2119: - viewer - an optional visualization context
2121: Notes:
2122: The available visualization contexts include
2123: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
2124: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2125: output where only the first processor opens
2126: the file. All other processors send their
2127: data to the first processor to print.
2129: You can change the format the vector is printed using the
2130: option PetscViewerSetFormat().
2132: The user can open alternative visualization contexts with
2133: + PetscViewerASCIIOpen() - Outputs vector to a specified file
2134: . PetscViewerBinaryOpen() - Outputs vector in binary to a
2135: specified file; corresponding input uses VecLoad()
2136: . PetscViewerDrawOpen() - Outputs vector to an X window display
2137: - PetscViewerSocketOpen() - Outputs vector to Socket viewer
2139: The user can call PetscViewerSetFormat() to specify the output
2140: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2141: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
2142: + PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2143: . PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2144: . PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2145: - PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
2146: format common among all vector types
2148: Level: beginner
2150: Concepts: vector^printing
2151: Concepts: vector^saving to disk
2153: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2154: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2155: PetscRealView(), PetscScalarView(), PetscIntView()
2156: @*/
2157: int VecView(Vec vec,PetscViewer viewer)
2158: {
2159: int ierr;
2160: PetscViewerFormat format;
2165: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
2168: if (vec->stash.n || vec->bstash.n) SETERRQ(1,"Must call VecAssemblyBegin/End() before viewing this vector");
2170: /*
2171: Check if default viewer has been overridden, but user request it anyways
2172: */
2173: PetscViewerGetFormat(viewer,&format);
2174: if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2175: PetscViewerPopFormat(viewer);
2176: (*vec->ops->viewnative)(vec,viewer);
2177: PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2178: } else {
2179: (*vec->ops->view)(vec,viewer);
2180: }
2181: return(0);
2182: }
2186: /*@
2187: VecGetSize - Returns the global number of elements of the vector.
2189: Not Collective
2191: Input Parameter:
2192: . x - the vector
2194: Output Parameters:
2195: . size - the global length of the vector
2197: Level: beginner
2199: Concepts: vector^local size
2201: .seealso: VecGetLocalSize()
2202: @*/
2203: int VecGetSize(Vec x,int *size)
2204: {
2211: (*x->ops->getsize)(x,size);
2212: return(0);
2213: }
2217: /*@
2218: VecGetLocalSize - Returns the number of elements of the vector stored
2219: in local memory. This routine may be implementation dependent, so use
2220: with care.
2222: Not Collective
2224: Input Parameter:
2225: . x - the vector
2227: Output Parameter:
2228: . size - the length of the local piece of the vector
2230: Level: beginner
2232: Concepts: vector^size
2234: .seealso: VecGetSize()
2235: @*/
2236: int VecGetLocalSize(Vec x,int *size)
2237: {
2244: (*x->ops->getlocalsize)(x,size);
2245: return(0);
2246: }
2250: /*@C
2251: VecGetOwnershipRange - Returns the range of indices owned by
2252: this processor, assuming that the vectors are laid out with the
2253: first n1 elements on the first processor, next n2 elements on the
2254: second, etc. For certain parallel layouts this range may not be
2255: well defined.
2257: Not Collective
2259: Input Parameter:
2260: . x - the vector
2262: Output Parameters:
2263: + low - the first local element, pass in PETSC_NULL if not interested
2264: - high - one more than the last local element, pass in PETSC_NULL if not interested
2266: Note:
2267: The high argument is one more than the last element stored locally.
2269: Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL
2271: Level: beginner
2273: Concepts: ownership^of vectors
2274: Concepts: vector^ownership of elements
2276: @*/
2277: int VecGetOwnershipRange(Vec x,int *low,int *high)
2278: {
2279: int ierr;
2286: PetscMapGetLocalRange(x->map,low,high);
2287: return(0);
2288: }
2292: /*@C
2293: VecGetPetscMap - Returns the map associated with the vector
2295: Not Collective
2297: Input Parameter:
2298: . x - the vector
2300: Output Parameters:
2301: . map - the map
2303: Level: developer
2305: @*/
2306: int VecGetPetscMap(Vec x,PetscMap *map)
2307: {
2311: *map = x->map;
2312: return(0);
2313: }
2317: /*@
2318: VecSetOption - Sets an option for controling a vector's behavior.
2320: Collective on Vec
2322: Input Parameter:
2323: + x - the vector
2324: - op - the option
2326: Supported Options:
2327: + VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
2328: entries destined to be stored on a seperate processor. This can be used
2329: to eliminate the global reduction in the VecAssemblyXXXX() if you know
2330: that you have only used VecSetValues() to set local elements
2331: - VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.
2333: Level: intermediate
2335: @*/
2336: int VecSetOption(Vec x,VecOption op)
2337: {
2343: if (x->ops->setoption) {
2344: (*x->ops->setoption)(x,op);
2345: }
2346: return(0);
2347: }
2351: /* Default routines for obtaining and releasing; */
2352: /* may be used by any implementation */
2353: int VecDuplicateVecs_Default(Vec w,int m,Vec *V[])
2354: {
2355: int i,ierr;
2360: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2361: PetscMalloc(m*sizeof(Vec*),V);
2362: for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2363: return(0);
2364: }
2368: int VecDestroyVecs_Default(const Vec v[], int m)
2369: {
2370: int i,ierr;
2374: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2375: for (i=0; i<m; i++) {VecDestroy(v[i]);}
2376: PetscFree((Vec*)v);
2377: return(0);
2378: }
2382: /*@
2383: VecPlaceArray - Allows one to replace the array in a vector with an
2384: array provided by the user. This is useful to avoid copying an array
2385: into a vector.
2387: Not Collective
2389: Input Parameters:
2390: + vec - the vector
2391: - array - the array
2393: Notes:
2394: You can return to the original array with a call to VecResetArray()
2396: Level: developer
2398: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
2400: @*/
2401: int VecPlaceArray(Vec vec,const PetscScalar array[])
2402: {
2408: if (vec->ops->placearray) {
2409: (*vec->ops->placearray)(vec,array);
2410: vec->normvalid = PETSC_FALSE;
2411: } else {
2412: SETERRQ(1,"Cannot place array in this type of vector");
2413: }
2414: return(0);
2415: }
2419: /*@
2420: VecResetArray - Resets a vector to use its default memory. Call this
2421: after the use of VecPlaceArray().
2423: Not Collective
2425: Input Parameters:
2426: . vec - the vector
2428: Level: developer
2430: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()
2432: @*/
2433: int VecResetArray(Vec vec)
2434: {
2440: if (vec->ops->resetarray) {
2441: (*vec->ops->resetarray)(vec);
2442: vec->normvalid = PETSC_FALSE;
2443: } else {
2444: SETERRQ(1,"Cannot reset array in this type of vector");
2445: }
2446: return(0);
2447: }
2451: /*@C
2452: VecReplaceArray - Allows one to replace the array in a vector with an
2453: array provided by the user. This is useful to avoid copying an array
2454: into a vector.
2456: Not Collective
2458: Input Parameters:
2459: + vec - the vector
2460: - array - the array
2462: Notes:
2463: This permanently replaces the array and frees the memory associated
2464: with the old array.
2466: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2467: freed by the user. It will be freed when the vector is destroy.
2469: Not supported from Fortran
2471: Level: developer
2473: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
2475: @*/
2476: int VecReplaceArray(Vec vec,const PetscScalar array[])
2477: {
2483: if (vec->ops->replacearray) {
2484: (*vec->ops->replacearray)(vec,array);
2485: vec->normvalid = PETSC_FALSE;
2486: } else {
2487: SETERRQ(1,"Cannot replace array in this type of vector");
2488: }
2489: return(0);
2490: }
2492: /*MC
2493: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2494: and makes them accessible via a Fortran90 pointer.
2496: Synopsis:
2497: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
2499: Collective on Vec
2501: Input Parameters:
2502: + x - a vector to mimic
2503: - n - the number of vectors to obtain
2505: Output Parameters:
2506: + y - Fortran90 pointer to the array of vectors
2507: - ierr - error code
2509: Example of Usage:
2510: .vb
2511: Vec x
2512: Vec, pointer :: y(:)
2513: ....
2514: call VecDuplicateVecsF90(x,2,y,ierr)
2515: call VecSet(alpha,y(2),ierr)
2516: call VecSet(alpha,y(2),ierr)
2517: ....
2518: call VecDestroyVecsF90(y,2,ierr)
2519: .ve
2521: Notes:
2522: Not yet supported for all F90 compilers
2524: Use VecDestroyVecsF90() to free the space.
2526: Level: beginner
2528: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
2530: M*/
2532: /*MC
2533: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2534: VecGetArrayF90().
2536: Synopsis:
2537: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2539: Not collective
2541: Input Parameters:
2542: + x - vector
2543: - xx_v - the Fortran90 pointer to the array
2545: Output Parameter:
2546: . ierr - error code
2548: Example of Usage:
2549: .vb
2550: PetscScalar, pointer :: xx_v(:)
2551: ....
2552: call VecGetArrayF90(x,xx_v,ierr)
2553: a = xx_v(3)
2554: call VecRestoreArrayF90(x,xx_v,ierr)
2555: .ve
2556:
2557: Notes:
2558: Not yet supported for all F90 compilers
2560: Level: beginner
2562: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray()
2564: M*/
2566: /*MC
2567: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
2569: Synopsis:
2570: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
2572: Input Parameters:
2573: + x - pointer to array of vector pointers
2574: - n - the number of vectors previously obtained
2576: Output Parameter:
2577: . ierr - error code
2579: Notes:
2580: Not yet supported for all F90 compilers
2582: Level: beginner
2584: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
2586: M*/
2588: /*MC
2589: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2590: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2591: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
2592: when you no longer need access to the array.
2594: Synopsis:
2595: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2597: Not Collective
2599: Input Parameter:
2600: . x - vector
2602: Output Parameters:
2603: + xx_v - the Fortran90 pointer to the array
2604: - ierr - error code
2606: Example of Usage:
2607: .vb
2608: PetscScalar, pointer :: xx_v(:)
2609: ....
2610: call VecGetArrayF90(x,xx_v,ierr)
2611: a = xx_v(3)
2612: call VecRestoreArrayF90(x,xx_v,ierr)
2613: .ve
2615: Notes:
2616: Not yet supported for all F90 compilers
2618: Level: beginner
2620: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()
2622: M*/
2626: /*@C
2627: VecLoadIntoVector - Loads a vector that has been stored in binary format
2628: with VecView().
2630: Collective on PetscViewer
2632: Input Parameters:
2633: + viewer - binary file viewer, obtained from PetscViewerBinaryOpen()
2634: - vec - vector to contain files values (must be of correct length)
2636: Level: intermediate
2638: Notes:
2639: The input file must contain the full global vector, as
2640: written by the routine VecView().
2642: Use VecLoad() to create the vector as the values are read in
2644: Notes for advanced users:
2645: Most users should not need to know the details of the binary storage
2646: format, since VecLoad() and VecView() completely hide these details.
2647: But for anyone who's interested, the standard binary matrix storage
2648: format is
2649: .vb
2650: int VEC_FILE_COOKIE
2651: int number of rows
2652: PetscScalar *values of all nonzeros
2653: .ve
2655: Note for Cray users, the int's stored in the binary file are 32 bit
2656: integers; not 64 as they are represented in the memory, so if you
2657: write your own routines to read/write these binary files from the Cray
2658: you need to adjust the integer sizes that you read in, see
2659: PetscReadBinary() and PetscWriteBinary() to see how this may be
2660: done.
2662: In addition, PETSc automatically does the byte swapping for
2663: machines that store the bytes reversed, e.g. DEC alpha, freebsd,
2664: linux, nt and the paragon; thus if you write your own binary
2665: read/write routines you have to swap the bytes; see PetscReadBinary()
2666: and PetscWriteBinary() to see how this may be done.
2668: Concepts: vector^loading from file
2670: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
2671: @*/
2672: int VecLoadIntoVector(PetscViewer viewer,Vec vec)
2673: {
2680: if (!vec->ops->loadintovector) {
2681: SETERRQ(1,"Vector does not support load");
2682: }
2683: (*vec->ops->loadintovector)(viewer,vec);
2684: vec->normvalid = PETSC_FALSE;
2685: return(0);
2686: }
2690: /*@
2691: VecReciprocal - Replaces each component of a vector by its reciprocal.
2693: Collective on Vec
2695: Input Parameter:
2696: . v - the vector
2698: Output Parameter:
2699: . v - the vector reciprocal
2701: Level: intermediate
2703: Concepts: vector^reciprocal
2705: @*/
2706: int VecReciprocal(Vec vec)
2707: {
2708: int ierr;
2713: if (!vec->ops->reciprocal) {
2714: SETERRQ(1,"Vector does not support reciprocal operation");
2715: }
2716: (*vec->ops->reciprocal)(vec);
2717: vec->normvalid = PETSC_FALSE;
2718: return(0);
2719: }
2723: int VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2724: {
2727: /* save the native version of the viewer */
2728: if (op == VECOP_VIEW && !vec->ops->viewnative) {
2729: vec->ops->viewnative = vec->ops->view;
2730: }
2731: (((void(**)(void))vec->ops)[(int)op]) = f;
2732: return(0);
2733: }
2737: /*@
2738: VecSetStashInitialSize - sets the sizes of the vec-stash, that is
2739: used during the assembly process to store values that belong to
2740: other processors.
2742: Collective on Vec
2744: Input Parameters:
2745: + vec - the vector
2746: . size - the initial size of the stash.
2747: - bsize - the initial size of the block-stash(if used).
2749: Options Database Keys:
2750: + -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2751: - -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
2753: Level: intermediate
2755: Notes:
2756: The block-stash is used for values set with VecSetValuesBlocked() while
2757: the stash is used for values set with VecSetValues()
2759: Run with the option -log_info and look for output of the form
2760: VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2761: to determine the appropriate value, MM, to use for size and
2762: VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2763: to determine the value, BMM to use for bsize
2765: Concepts: vector^stash
2766: Concepts: stash^vector
2768: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()
2770: @*/
2771: int VecSetStashInitialSize(Vec vec,int size,int bsize)
2772: {
2777: VecStashSetInitialSize_Private(&vec->stash,size);
2778: VecStashSetInitialSize_Private(&vec->bstash,bsize);
2779: return(0);
2780: }
2784: /*@
2785: VecStashView - Prints the entries in the vector stash and block stash.
2787: Collective on Vec
2789: Input Parameters:
2790: + vec - the vector
2791: - viewer - the viewer
2793: Level: advanced
2795: Concepts: vector^stash
2796: Concepts: stash^vector
2798: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()
2800: @*/
2801: int VecStashView(Vec v,PetscViewer viewer)
2802: {
2803: int ierr,rank,i,j;
2804: PetscTruth match;
2805: VecStash *s;
2806: PetscScalar val;
2813: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
2814: if (!match) SETERRQ1(1,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
2815: PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
2816: MPI_Comm_rank(v->comm,&rank);
2817: s = &v->bstash;
2819: /* print block stash */
2820: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %d block size %d\n",rank,s->n,s->bs);
2821: for (i=0; i<s->n; i++) {
2822: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d ",rank,s->idx[i]);
2823: for (j=0; j<s->bs; j++) {
2824: val = s->array[i*s->bs+j];
2825: #if defined(PETSC_USE_COMPLEX)
2826: PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
2827: #else
2828: PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
2829: #endif
2830: }
2831: PetscViewerASCIISynchronizedPrintf(viewer,"\n");
2832: }
2833: PetscViewerFlush(viewer);
2835: s = &v->stash;
2837: /* print basic stash */
2838: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %d\n",rank,s->n);
2839: for (i=0; i<s->n; i++) {
2840: val = s->array[i];
2841: #if defined(PETSC_USE_COMPLEX)
2842: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
2843: #else
2844: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d %18.16e\n",rank,s->idx[i],val);
2845: #endif
2846: }
2847: PetscViewerFlush(viewer);
2849: PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
2850: return(0);
2851: }
2855: /*@C
2856: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
2857: processor's portion of the vector data. You MUST call VecRestoreArray2d()
2858: when you no longer need access to the array.
2860: Not Collective
2862: Input Parameter:
2863: + x - the vector
2864: . m - first dimension of two dimensional array
2865: . n - second dimension of two dimensional array
2866: . mstart - first index you will use in first coordinate direction (often 0)
2867: - nstart - first index in the second coordinate direction (often 0)
2869: Output Parameter:
2870: . a - location to put pointer to the array
2872: Level: beginner
2874: Notes:
2875: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
2876: obtained from the corner indices obtained from DAGetGhostCorners() while for
2877: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
2878: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
2879:
2880: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2882: Concepts: vector^accessing local values as 2d array
2884: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2885: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2886: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2887: @*/
2888: int VecGetArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
2889: {
2890: int i,ierr,N;
2891: PetscScalar *aa;
2897: VecGetLocalSize(x,&N);
2898: if (m*n != N) SETERRQ3(1,"Local array size %d does not match 2d array dimensions %d by %d",N,m,n);
2899: VecGetArray(x,&aa);
2901: PetscMalloc(m*sizeof(PetscScalar*),a);
2902: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
2903: *a -= mstart;
2904: return(0);
2905: }
2909: /*@C
2910: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
2912: Not Collective
2914: Input Parameters:
2915: + x - the vector
2916: . m - first dimension of two dimensional array
2917: . n - second dimension of the two dimensional array
2918: . mstart - first index you will use in first coordinate direction (often 0)
2919: . nstart - first index in the second coordinate direction (often 0)
2920: - a - location of pointer to array obtained from VecGetArray2d()
2922: Level: beginner
2924: Notes:
2925: For regular PETSc vectors this routine does not involve any copies. For
2926: any special vectors that do not store local vector data in a contiguous
2927: array, this routine will copy the data back into the underlying
2928: vector data structure from the array obtained with VecGetArray().
2930: This routine actually zeros out the a pointer.
2932: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2933: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
2934: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2935: @*/
2936: int VecRestoreArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
2937: {
2943: PetscFree(*a + mstart);
2944: VecRestoreArray(x,PETSC_NULL);
2945: return(0);
2946: }
2950: /*@C
2951: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
2952: processor's portion of the vector data. You MUST call VecRestoreArray1d()
2953: when you no longer need access to the array.
2955: Not Collective
2957: Input Parameter:
2958: + x - the vector
2959: . m - first dimension of two dimensional array
2960: - mstart - first index you will use in first coordinate direction (often 0)
2962: Output Parameter:
2963: . a - location to put pointer to the array
2965: Level: beginner
2967: Notes:
2968: For a vector obtained from DACreateLocalVector() mstart are likely
2969: obtained from the corner indices obtained from DAGetGhostCorners() while for
2970: DACreateGlobalVector() they are the corner indices from DAGetCorners().
2971:
2972: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2974: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2975: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2976: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2977: @*/
2978: int VecGetArray1d(Vec x,int m,int mstart,PetscScalar *a[])
2979: {
2980: int ierr,N;
2986: VecGetLocalSize(x,&N);
2987: if (m != N) SETERRQ2(1,"Local array size %d does not match 1d array dimensions %d",N,m);
2988: VecGetArray(x,a);
2989: *a -= mstart;
2990: return(0);
2991: }
2995: /*@C
2996: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
2998: Not Collective
3000: Input Parameters:
3001: + x - the vector
3002: . m - first dimension of two dimensional array
3003: . mstart - first index you will use in first coordinate direction (often 0)
3004: - a - location of pointer to array obtained from VecGetArray21()
3006: Level: beginner
3008: Notes:
3009: For regular PETSc vectors this routine does not involve any copies. For
3010: any special vectors that do not store local vector data in a contiguous
3011: array, this routine will copy the data back into the underlying
3012: vector data structure from the array obtained with VecGetArray1d().
3014: This routine actually zeros out the a pointer.
3016: Concepts: vector^accessing local values as 1d array
3018: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3019: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3020: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3021: @*/
3022: int VecRestoreArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3023: {
3029: VecRestoreArray(x,PETSC_NULL);
3030: return(0);
3031: }
3035: /*@C
3036: VecConjugate - Conjugates a vector.
3038: Collective on Vec
3040: Input Parameters:
3041: . x - the vector
3043: Level: intermediate
3045: Concepts: vector^conjugate
3047: @*/
3048: int VecConjugate(Vec x)
3049: {
3050: #ifdef PETSC_USE_COMPLEX
3056: (*x->ops->conjugate)(x);
3057: x->normvalid = PETSC_FALSE;
3058: return(0);
3059: #else
3060: return(0);
3061: #endif
3062: }
3066: /*@C
3067: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
3068: processor's portion of the vector data. You MUST call VecRestoreArray3d()
3069: when you no longer need access to the array.
3071: Not Collective
3073: Input Parameter:
3074: + x - the vector
3075: . m - first dimension of three dimensional array
3076: . n - second dimension of three dimensional array
3077: . p - third dimension of three dimensional array
3078: . mstart - first index you will use in first coordinate direction (often 0)
3079: . nstart - first index in the second coordinate direction (often 0)
3080: - pstart - first index in the third coordinate direction (often 0)
3082: Output Parameter:
3083: . a - location to put pointer to the array
3085: Level: beginner
3087: Notes:
3088: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3089: obtained from the corner indices obtained from DAGetGhostCorners() while for
3090: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3091: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3092:
3093: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3095: Concepts: vector^accessing local values as 3d array
3097: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3098: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3099: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3100: @*/
3101: int VecGetArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3102: {
3103: int i,ierr,N,j;
3104: PetscScalar *aa,**b;
3110: VecGetLocalSize(x,&N);
3111: if (m*n*p != N) SETERRQ4(1,"Local array size %d does not match 3d array dimensions %d by %d by %d",N,m,n,p);
3112: VecGetArray(x,&aa);
3114: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3115: b = (PetscScalar **)((*a) + m);
3116: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3117: for (i=0; i<m; i++) {
3118: for (j=0; j<n; j++) {
3119: b[i*n+j] = aa + i*n*p + j*p - pstart;
3120: }
3121: }
3122: *a -= mstart;
3123: return(0);
3124: }
3128: /*@C
3129: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
3131: Not Collective
3133: Input Parameters:
3134: + x - the vector
3135: . m - first dimension of three dimensional array
3136: . n - second dimension of the three dimensional array
3137: . p - third dimension of the three dimensional array
3138: . mstart - first index you will use in first coordinate direction (often 0)
3139: . nstart - first index in the second coordinate direction (often 0)
3140: . pstart - first index in the third coordinate direction (often 0)
3141: - a - location of pointer to array obtained from VecGetArray3d()
3143: Level: beginner
3145: Notes:
3146: For regular PETSc vectors this routine does not involve any copies. For
3147: any special vectors that do not store local vector data in a contiguous
3148: array, this routine will copy the data back into the underlying
3149: vector data structure from the array obtained with VecGetArray().
3151: This routine actually zeros out the a pointer.
3153: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3154: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3155: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3156: @*/
3157: int VecRestoreArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3158: {
3164: PetscFree(*a + mstart);
3165: VecRestoreArray(x,PETSC_NULL);
3166: return(0);
3167: }