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 vecimpl.h
8: /* Logging support */
9: int VEC_COOKIE = 0;
10: int VEC_View = 0, VEC_Max = 0, VEC_Min = 0, VEC_DotBarrier = 0, VEC_Dot = 0, VEC_MDotBarrier = 0, VEC_MDot = 0, VEC_TDot = 0, VEC_MTDot = 0, VEC_NormBarrier = 0;
11: int VEC_Norm = 0, VEC_Normalize = 0, VEC_Scale = 0, VEC_Copy = 0, VEC_Set = 0, VEC_AXPY = 0, VEC_AYPX = 0, VEC_WAXPY = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0;
12: int VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
13: int VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;
15: /* ugly globals for VecSetValue() and VecSetValueLocal() */
16: int VecSetValue_Row = 0;
17: PetscScalar VecSetValue_Value = 0.0;
21: /*
22: VecSetTypeFromOptions_Private - Sets the type of vector from user options. Defaults to a PETSc sequential vector on one
23: processor and a PETSc MPI vector on more than one processor.
25: Collective on Vec
27: Input Parameter:
28: . vec - The vector
30: Level: intermediate
32: .keywords: Vec, set, options, database, type
33: .seealso: VecSetFromOptions(), VecSetType()
34: */
35: static int VecSetTypeFromOptions_Private(Vec vec)
36: {
37: PetscTruth opt;
38: const char *defaultType;
39: char typeName[256];
40: int numProcs;
41: int ierr;
44: if (vec->type_name != PETSC_NULL) {
45: defaultType = vec->type_name;
46: } else {
47: MPI_Comm_size(vec->comm, &numProcs);
48: if (numProcs > 1) {
49: defaultType = VECMPI;
50: } else {
51: defaultType = VECSEQ;
52: }
53: }
55: if (!VecRegisterAllCalled) {
56: VecRegisterAll(PETSC_NULL);
57: }
58: PetscOptionsList("-vec_type", "Vector type"," VecSetType", VecList, defaultType, typeName, 256, &opt);
59:
60: if (opt == PETSC_TRUE) {
61: VecSetType(vec, typeName);
62: } else {
63: VecSetType(vec, defaultType);
64: }
65: return(0);
66: }
70: /*@C
71: VecSetFromOptions - Configures the vector from the options database.
73: Collective on Vec
75: Input Parameter:
76: . vec - The vector
78: Notes: To see all options, run your program with the -help option, or consult the users manual.
79: Must be called after VecCreate() but before the vector is used.
81: Level: beginner
83: Concepts: vectors^setting options
84: Concepts: vectors^setting type
86: .keywords: Vec, set, options, database
87: .seealso: VecCreate(), VecPrintHelp(), VechSetOptionsPrefix()
88: @*/
89: int VecSetFromOptions(Vec vec)
90: {
91: PetscTruth opt;
92: int ierr;
97: PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");
99: /* Handle generic vector options */
100: PetscOptionsHasName(PETSC_NULL, "-help", &opt);
101: if (opt == PETSC_TRUE) {
102: VecPrintHelp(vec);
103: }
105: /* Handle vector type options */
106: VecSetTypeFromOptions_Private(vec);
108: /* Handle specific vector options */
109: if (vec->ops->setfromoptions != PETSC_NULL) {
110: (*vec->ops->setfromoptions)(vec);
111: }
112: PetscOptionsEnd();
114: #if defined(__cplusplus) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE) && defined(PETSC_HAVE_CXX_NAMESPACE)
115: VecESISetFromOptions(vec);
116: #endif
118: VecViewFromOptions(vec, vec->name);
119: return(0);
120: }
124: /*@
125: VecPrintHelp - Prints some options for the Vec.
127: Input Parameter:
128: . vec - The vector
130: Options Database Keys:
131: $ -help, -h
133: Level: intermediate
135: .keywords: Vec, help
136: .seealso: VecSetFromOptions()
137: @*/
138: int VecPrintHelp(Vec vec)
139: {
142: return(0);
143: }
147: /*@
148: VecSetSizes - Sets the local and global sizes, and checks to determine compatibility
150: Collective on Vec
152: Input Parameters:
153: + v - the vector
154: . n - the local size (or PETSC_DECIDE to have it set)
155: - N - the global size (or PETSC_DECIDE)
157: Notes:
158: n and N cannot be both PETSC_DECIDE
159: If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.
161: Level: intermediate
163: .seealso: VecGetSize(), PetscSplitOwnership()
164: @*/
165: int VecSetSizes(Vec v, int n, int N)
166: {
169: v->n = n;
170: v->N = N;
171: return(0);
172: }
176: /*@
177: VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
178: and VecSetValuesBlockedLocal().
180: Collective on Vec
182: Input Parameter:
183: + v - the vector
184: - bs - the blocksize
186: Notes:
187: All vectors obtained by VecDuplicate() inherit the same blocksize.
189: Level: advanced
191: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecGetBlockSize()
193: Concepts: block size^vectors
194: @*/
195: int VecSetBlockSize(Vec v,int bs)
196: {
199: if (bs <= 0) bs = 1;
200: if (bs == v->bs) return(0);
201: if (v->bs != -1) SETERRQ2(PETSC_ERR_ARG_WRONGSTATE,"Cannot reset blocksize. Current size %d new %d",v->bs,bs);
202: if (v->N != -1 && v->N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %d %d",v->N,bs);
203: if (v->n != -1 && v->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %d %d\n\
204: Try setting blocksize before setting the vector type",v->n,bs);
205:
206: v->bs = bs;
207: v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
208: return(0);
209: }
213: /*@
214: VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
215: and VecSetValuesBlockedLocal().
217: Collective on Vec
219: Input Parameter:
220: . v - the vector
222: Output Parameter:
223: . bs - the blocksize
225: Notes:
226: All vectors obtained by VecDuplicate() inherit the same blocksize.
228: Level: advanced
230: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecSetBlockSize()
232: Concepts: vector^block size
233: Concepts: block^vector
235: @*/
236: int VecGetBlockSize(Vec v,int *bs)
237: {
241: *bs = v->bs;
242: return(0);
243: }
247: /*@
248: VecValid - Checks whether a vector object is valid.
250: Not Collective
252: Input Parameter:
253: . v - the object to check
255: Output Parameter:
256: flg - flag indicating vector status, either
257: PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.
259: Level: developer
261: @*/
262: int VecValid(Vec v,PetscTruth *flg)
263: {
266: if (!v) *flg = PETSC_FALSE;
267: else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
268: else *flg = PETSC_TRUE;
269: return(0);
270: }
274: /*@
275: VecDot - Computes the vector dot product.
277: Collective on Vec
279: Input Parameters:
280: . x, y - the vectors
282: Output Parameter:
283: . alpha - the dot product
285: Performance Issues:
286: + per-processor memory bandwidth
287: . interprocessor latency
288: - work load inbalance that causes certain processes to arrive much earlier than
289: others
291: Notes for Users of Complex Numbers:
292: For complex vectors, VecDot() computes
293: $ val = (x,y) = y^H x,
294: where y^H denotes the conjugate transpose of y.
296: Use VecTDot() for the indefinite form
297: $ val = (x,y) = y^T x,
298: where y^T denotes the transpose of y.
300: Level: intermediate
302: Concepts: inner product
303: Concepts: vector^inner product
305: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
306: @*/
307: int VecDot(Vec x,Vec y,PetscScalar *val)
308: {
318: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
319: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
321: PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
322: (*x->ops->dot)(x,y,val);
323: PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
324: /*
325: The next block is for incremental debugging
326: */
327: if (PetscCompare) {
328: int flag;
329: MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
330: if (flag != MPI_UNEQUAL) {
331: PetscCompareScalar(*val);
332: }
333: }
334: return(0);
335: }
339: /*@
340: VecNorm - Computes the vector norm.
342: Collective on Vec
344: Input Parameters:
345: + x - the vector
346: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
347: NORM_1_AND_2, which computes both norms and stores them
348: in a two element array.
350: Output Parameter:
351: . val - the norm
353: Notes:
354: $ NORM_1 denotes sum_i |x_i|
355: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
356: $ NORM_INFINITY denotes max_i |x_i|
358: Level: intermediate
360: Performance Issues:
361: + per-processor memory bandwidth
362: . interprocessor latency
363: - work load inbalance that causes certain processes to arrive much earlier than
364: others
366: Compile Option:
367: PETSC_HAVE_SLOW_NRM2 will cause a C (loop unrolled) version of the norm to be used, rather
368: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
369: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
371: Concepts: norm
372: Concepts: vector^norm
374: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(),
375: VecNormBegin(), VecNormEnd()
377: @*/
378: int VecNorm(Vec x,NormType type,PetscReal *val)
379: {
380: PetscTruth flg;
381: int type_id, ierr;
388: /*
389: * Cached data?
390: */
391: VecNormComposedDataID(type,&type_id);
392: PetscObjectGetRealComposedData((PetscObject)x,type_id,*val,flg);
393: if (flg) return(0);
394:
396: PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
397: (*x->ops->norm)(x,type,val);
398: PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);
400: /*
401: The next block is for incremental debugging
402: */
403: if (PetscCompare) {
404: int flag;
405: MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
406: if (flag != MPI_UNEQUAL) {
407: PetscCompareDouble(*val);
408: }
409: }
411: if (type!=NORM_1_AND_2) {
412: PetscObjectSetRealComposedData((PetscObject)x,type_id,*val);
413: }
415: return(0);
416: }
420: int VecNormComposedDataID(NormType type,int *type_id)
421: {
422: static int id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
425: switch (type) {
426: case NORM_1 :
427: if (id_norm1==-1) {
428: PetscRegisterComposedData(&id_norm1); }
429: *type_id = id_norm1; break;
430: case NORM_2 :
431: if (id_norm2==-1) {
432: PetscRegisterComposedData(&id_norm2); }
433: *type_id = id_norm2; break;
434: case NORM_1_AND_2 :
435: /* we don't handle this one yet */
436: if (id_norm1==-1) {
437: PetscRegisterComposedData(&id_norm1); }
438: if (id_norm2==-1) {
439: PetscRegisterComposedData(&id_norm2); }
440: *type_id = id_norm12; break;
441: case NORM_INFINITY :
442: if (id_normInf==-1) {
443: PetscRegisterComposedData(&id_normInf); }
444: *type_id = id_normInf; break;
445: case NORM_FROBENIUS :
446: if (id_normF==-1) {
447: PetscRegisterComposedData(&id_normF); }
448: *type_id = id_normF; break;
449: }
450: return(0);
451: }
455: /*@
456: VecNormalize - Normalizes a vector by 2-norm.
458: Collective on Vec
460: Input Parameters:
461: + x - the vector
463: Output Parameter:
464: . x - the normalized vector
465: - val - the vector norm before normalization
467: Level: intermediate
469: Concepts: vector^normalizing
470: Concepts: normalizing^vector
472: @*/
473: int VecNormalize (Vec x,PetscReal *val)
474: {
481: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
482: VecNorm(x,NORM_2,val);
483: if (*val == 0.0) {
484: PetscLogInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm");
485: } else {
486: PetscScalar tmp = 1.0/(*val);
487: VecScale(&tmp,x);
488: }
490: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
491: return(0);
492: }
496: /*@C
497: VecMax - Determines the maximum vector component and its location.
499: Collective on Vec
501: Input Parameter:
502: . x - the vector
504: Output Parameters:
505: + val - the maximum component
506: - p - the location of val
508: Notes:
509: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
511: Level: intermediate
513: Concepts: maximum^of vector
514: Concepts: vector^maximum value
516: .seealso: VecNorm(), VecMin()
517: @*/
518: int VecMax(Vec x,int *p,PetscReal *val)
519: {
526: PetscLogEventBegin(VEC_Max,x,0,0,0);
527: (*x->ops->max)(x,p,val);
528: PetscLogEventEnd(VEC_Max,x,0,0,0);
529: return(0);
530: }
534: /*@
535: VecMin - Determines the minimum vector component and its location.
537: Collective on Vec
539: Input Parameters:
540: . x - the vector
542: Output Parameter:
543: + val - the minimum component
544: - p - the location of val
546: Level: intermediate
548: Notes:
549: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
551: Concepts: minimum^of vector
552: Concepts: vector^minimum entry
554: .seealso: VecMax()
555: @*/
556: int VecMin(Vec x,int *p,PetscReal *val)
557: {
564: PetscLogEventBegin(VEC_Min,x,0,0,0);
565: (*x->ops->min)(x,p,val);
566: PetscLogEventEnd(VEC_Min,x,0,0,0);
567: return(0);
568: }
572: /*@
573: VecTDot - Computes an indefinite vector dot product. That is, this
574: routine does NOT use the complex conjugate.
576: Collective on Vec
578: Input Parameters:
579: . x, y - the vectors
581: Output Parameter:
582: . val - the dot product
584: Notes for Users of Complex Numbers:
585: For complex vectors, VecTDot() computes the indefinite form
586: $ val = (x,y) = y^T x,
587: where y^T denotes the transpose of y.
589: Use VecDot() for the inner product
590: $ val = (x,y) = y^H x,
591: where y^H denotes the conjugate transpose of y.
593: Level: intermediate
595: Concepts: inner product^non-Hermitian
596: Concepts: vector^inner product
597: Concepts: non-Hermitian inner product
599: .seealso: VecDot(), VecMTDot()
600: @*/
601: int VecTDot(Vec x,Vec y,PetscScalar *val)
602: {
612: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
613: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
615: PetscLogEventBegin(VEC_TDot,x,y,0,0);
616: (*x->ops->tdot)(x,y,val);
617: PetscLogEventEnd(VEC_TDot,x,y,0,0);
618: return(0);
619: }
623: /*@
624: VecScale - Scales a vector.
626: Collective on Vec
628: Input Parameters:
629: + x - the vector
630: - alpha - the scalar
632: Output Parameter:
633: . x - the scaled vector
635: Note:
636: For a vector with n components, VecScale() computes
637: $ x[i] = alpha * x[i], for i=1,...,n.
639: Level: intermediate
641: Concepts: vector^scaling
642: Concepts: scaling^vector
644: @*/
645: int VecScale (const PetscScalar *alpha,Vec x)
646: {
647: PetscReal scale,norm1=0.0,norm2=0.0,normInf=0.0,normF=0.0;
648: PetscTruth flg1,flg2,flgInf,flgF;
649: int type_id1,type_id2,type_idInf,type_idF,ierr;
655: PetscLogEventBegin(VEC_Scale,x,0,0,0);
656: (*x->ops->scale)(alpha,x);
658: /*
659: * Update cached data
660: */
661: /* see if we have cached norms */
662: /* 1 */
663: VecNormComposedDataID(NORM_1,&type_id1);
664: PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1,flg1);
665: /* 2 */
666: VecNormComposedDataID(NORM_2,&type_id2);
667: PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2,flg2);
668: /* inf */
669: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
670: PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInf,flgInf);
671: /* frobenius */
672: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
673: PetscObjectGetRealComposedData((PetscObject)x,type_idF,normF,flgF);
675: /* in general we consider this object touched */
676: PetscObjectIncreaseState((PetscObject)x);
678: /* however, norms can be simply updated */
679: scale = PetscAbsScalar(*alpha);
680: /* 1 */
681: if (flg1) {
682: PetscObjectSetRealComposedData((PetscObject)x,type_id1,scale*norm1);
683: }
684: /* 2 */
685: if (flg2) {
686: PetscObjectSetRealComposedData((PetscObject)x,type_id2,scale*norm2);
687: }
688: /* inf */
689: if (flgInf) {
690: PetscObjectSetRealComposedData((PetscObject)x,type_idInf,scale*normInf);
691: }
692: /* frobenius */
693: if (flgF) {
694: PetscObjectSetRealComposedData((PetscObject)x,type_idF,scale*normF);
695: }
697: PetscLogEventEnd(VEC_Scale,x,0,0,0);
698: return(0);
699: }
703: /*@
704: VecCopy - Copies a vector.
706: Collective on Vec
708: Input Parameter:
709: . x - the vector
711: Output Parameter:
712: . y - the copy
714: Notes:
715: For default parallel PETSc vectors, both x and y must be distributed in
716: the same manner; local copies are done.
718: Level: beginner
720: .seealso: VecDuplicate()
721: @*/
722: int VecCopy(Vec x,Vec y)
723: {
724: PetscTruth flg;
725: PetscReal norm=0.0;
726: int type_id,ierr;
734: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
735: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
737: PetscLogEventBegin(VEC_Copy,x,y,0,0);
738: (*x->ops->copy)(x,y);
740: /*
741: * Update cached data
742: */
743: /* in general we consider this object touched */
744: PetscObjectIncreaseState((PetscObject)y);
745: /* however, norms can be simply copied over */
746: /* 2 */
747: VecNormComposedDataID(NORM_2,&type_id);
748: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
749: if (flg) {
750: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
751: }
752: /* 1 */
753: VecNormComposedDataID(NORM_1,&type_id);
754: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
755: if (flg) {
756: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
757: }
758: /* inf */
759: VecNormComposedDataID(NORM_INFINITY,&type_id);
760: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
761: if (flg) {
762: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
763: }
764: /* frobenius */
765: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
766: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
767: if (flg) {
768: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
769: }
771: PetscLogEventEnd(VEC_Copy,x,y,0,0);
772: return(0);
773: }
777: /*@
778: VecSet - Sets all components of a vector to a single scalar value.
780: Collective on Vec
782: Input Parameters:
783: + alpha - the scalar
784: - x - the vector
786: Output Parameter:
787: . x - the vector
789: Note:
790: For a vector of dimension n, VecSet() computes
791: $ x[i] = alpha, for i=1,...,n,
792: so that all vector entries then equal the identical
793: scalar value, alpha. Use the more general routine
794: VecSetValues() to set different vector entries.
796: Level: beginner
798: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
800: Concepts: vector^setting to constant
802: @*/
803: int VecSet(const PetscScalar *alpha,Vec x)
804: {
805: PetscReal val;
806: int type_id,ierr;
813: PetscLogEventBegin(VEC_Set,x,0,0,0);
814: (*x->ops->set)(alpha,x);
815: PetscLogEventEnd(VEC_Set,x,0,0,0);
817: /*
818: * Update cached data
819: */
820: /* in general we consider this object touched */
821: PetscObjectIncreaseState((PetscObject)x);
822: /* however, norms can be simply set */
823: /* 1 */
824: val = PetscAbsScalar(*alpha);
825: VecNormComposedDataID(NORM_1,&type_id);
826: PetscObjectSetRealComposedData((PetscObject)x,type_id,x->N * val);
827: /* inf */
828: VecNormComposedDataID(NORM_INFINITY,&type_id);
829: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
830: /* 2 */
831: val = sqrt((double)x->N) * val;
832: VecNormComposedDataID(NORM_2,&type_id);
833: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
834: /* frobenius */
835: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
836: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
838: return(0);
839: }
843: /*@C
844: VecSetRandom - Sets all components of a vector to random numbers.
846: Collective on Vec
848: Input Parameters:
849: + rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
850: it will create one internally.
851: - x - the vector
853: Output Parameter:
854: . x - the vector
856: Example of Usage:
857: .vb
858: PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
859: VecSetRandom(rctx,x);
860: PetscRandomDestroy(rctx);
861: .ve
863: Level: intermediate
865: Concepts: vector^setting to random
866: Concepts: random^vector
868: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
869: @*/
870: int VecSetRandom(PetscRandom rctx,Vec x)
871: {
872: int ierr;
873: PetscRandom randObj = PETSC_NULL;
880: if (!rctx) {
881: MPI_Comm comm;
882: PetscObjectGetComm((PetscObject)x,&comm);
883: PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
884: rctx = randObj;
885: }
887: PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
888: (*x->ops->setrandom)(rctx,x);
889: PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
890:
891: if (randObj) {
892: PetscRandomDestroy(randObj);
893: }
894: PetscObjectIncreaseState((PetscObject)x);
895: return(0);
896: }
900: /*@
901: VecAXPY - Computes y = alpha x + y.
903: Collective on Vec
905: Input Parameters:
906: + alpha - the scalar
907: - x, y - the vectors
909: Output Parameter:
910: . y - output vector
912: Level: intermediate
914: Concepts: vector^BLAS
915: Concepts: BLAS
917: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
918: @*/
919: int VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
920: {
930: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
931: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
933: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
934: (*x->ops->axpy)(alpha,x,y);
935: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
936: PetscObjectIncreaseState((PetscObject)y);
937: return(0);
938: }
942: /*@
943: VecAXPBY - Computes y = alpha x + beta y.
945: Collective on Vec
947: Input Parameters:
948: + alpha,beta - the scalars
949: - x, y - the vectors
951: Output Parameter:
952: . y - output vector
954: Level: intermediate
956: Concepts: BLAS
957: Concepts: vector^BLAS
959: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
960: @*/
961: int VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
962: {
973: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
974: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
976: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
977: (*x->ops->axpby)(alpha,beta,x,y);
978: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
979: PetscObjectIncreaseState((PetscObject)y);
980: return(0);
981: }
985: /*@
986: VecAYPX - Computes y = x + alpha y.
988: Collective on Vec
990: Input Parameters:
991: + alpha - the scalar
992: - x, y - the vectors
994: Output Parameter:
995: . y - output vector
997: Level: intermediate
999: Concepts: vector^BLAS
1000: Concepts: BLAS
1002: .seealso: VecAXPY(), VecWAXPY()
1003: @*/
1004: int VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
1005: {
1015: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1016: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1018: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1019: (*x->ops->aypx)(alpha,x,y);
1020: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1021: PetscObjectIncreaseState((PetscObject)y);
1022: return(0);
1023: }
1027: /*@
1028: VecSwap - Swaps the vectors x and y.
1030: Collective on Vec
1032: Input Parameters:
1033: . x, y - the vectors
1035: Level: advanced
1037: Concepts: vector^swapping values
1039: @*/
1040: int VecSwap(Vec x,Vec y)
1041: {
1042: PetscReal norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1043: PetscReal norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1044: PetscTruth flg1x,flg2x,flgInfx,flgFx;
1045: PetscTruth flg1y,flg2y,flgInfy,flgFy;
1046: int type_id1,type_id2,type_idInf,type_idF;
1047: int ierr;
1055: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1056: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1058: PetscLogEventBegin(VEC_Swap,x,y,0,0);
1060: /* See if we have cached norms */
1061: /* 1 */
1062: VecNormComposedDataID(NORM_1,&type_id1);
1063: PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1x,flg1x);
1064: PetscObjectGetRealComposedData((PetscObject)y,type_id1,norm1y,flg1y);
1065: /* 2 */
1066: VecNormComposedDataID(NORM_2,&type_id2);
1067: PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2x,flg2x);
1068: PetscObjectGetRealComposedData((PetscObject)y,type_id2,norm2y,flg2y);
1069: /* inf */
1070: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1071: PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInfx,flgInfx);
1072: PetscObjectGetRealComposedData((PetscObject)y,type_idInf,normInfy,flgInfy);
1073: /* frobenius */
1074: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1075: PetscObjectGetRealComposedData((PetscObject)x,type_idF,normFx,flgFx);
1076: PetscObjectGetRealComposedData((PetscObject)y,type_idF,normFy,flgFy);
1078: /* Do the actual swap */
1079: (*x->ops->swap)(x,y);
1080: PetscObjectIncreaseState((PetscObject)x);
1081: PetscObjectIncreaseState((PetscObject)y);
1083: /* Swap any cached norms */
1084: /* 1 */
1085: if (flg1x) {
1086: PetscObjectSetRealComposedData((PetscObject)y,type_id1,norm1x);
1087: }
1088: if (flg1y) {
1089: PetscObjectSetRealComposedData((PetscObject)x,type_id1,norm1y);
1090: }
1091: /* 2 */
1092: if (flg2x) {
1093: PetscObjectSetRealComposedData((PetscObject)y,type_id2,norm2x);
1094: }
1095: if (flg2y) {
1096: PetscObjectSetRealComposedData((PetscObject)x,type_id2,norm2y);
1097: }
1098: /* inf */
1099: if (flgInfx) {
1100: PetscObjectSetRealComposedData((PetscObject)y,type_idInf,normInfx);
1101: }
1102: if (flgInfy) {
1103: PetscObjectSetRealComposedData((PetscObject)x,type_idInf,normInfy);
1104: }
1105: /* frobenius */
1106: if (flgFx) {
1107: PetscObjectSetRealComposedData((PetscObject)y,type_idF,normFx);
1108: }
1109: if (flgFy) {
1110: PetscObjectSetRealComposedData((PetscObject)x,type_idF,normFy);
1111: }
1113: PetscLogEventEnd(VEC_Swap,x,y,0,0);
1115: return(0);
1116: }
1120: /*@
1121: VecWAXPY - Computes w = alpha x + y.
1123: Collective on Vec
1125: Input Parameters:
1126: + alpha - the scalar
1127: - x, y - the vectors
1129: Output Parameter:
1130: . w - the result
1132: Level: intermediate
1134: Concepts: vector^BLAS
1135: Concepts: BLAS
1137: .seealso: VecAXPY(), VecAYPX()
1138: @*/
1139: int VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
1140: {
1153: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1154: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1156: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1157: (*x->ops->waxpy)(alpha,x,y,w);
1158: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1159: PetscObjectIncreaseState((PetscObject)w);
1160: return(0);
1161: }
1165: /*@
1166: VecPointwiseMult - Computes the componentwise multiplication w = x*y.
1168: Collective on Vec
1170: Input Parameters:
1171: . x, y - the vectors
1173: Output Parameter:
1174: . w - the result
1176: Level: advanced
1178: Notes: any subset of the x, y, and w may be the same vector.
1180: Concepts: vector^pointwise multiply
1182: .seealso: VecPointwiseDivide()
1183: @*/
1184: int VecPointwiseMult(Vec x,Vec y,Vec w)
1185: {
1197: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1198: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1200: PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1201: (*x->ops->pointwisemult)(x,y,w);
1202: PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1203: PetscObjectIncreaseState((PetscObject)w);
1204: return(0);
1205: }
1209: /*@
1210: VecPointwiseDivide - Computes the componentwise division w = x/y.
1212: Collective on Vec
1214: Input Parameters:
1215: . x, y - the vectors
1217: Output Parameter:
1218: . w - the result
1220: Level: advanced
1222: Notes: any subset of the x, y, and w may be the same vector.
1224: Concepts: vector^pointwise divide
1226: .seealso: VecPointwiseMult()
1227: @*/
1228: int VecPointwiseDivide(Vec x,Vec y,Vec w)
1229: {
1241: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1242: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1244: (*x->ops->pointwisedivide)(x,y,w);
1245: PetscObjectIncreaseState((PetscObject)w);
1246: return(0);
1247: }
1251: /*@
1252: VecMaxPointwiseDivide - Computes the maximum of the componentwise division w = abs(x/y).
1254: Collective on Vec
1256: Input Parameters:
1257: . x, y - the vectors
1259: Output Parameter:
1260: . max - the result
1262: Level: advanced
1264: Notes: any subset of the x, y, and w may be the same vector.
1266: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1267: @*/
1268: int VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1269: {
1279: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1280: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1282: (*x->ops->maxpointwisedivide)(x,y,max);
1283: return(0);
1284: }
1288: /*@C
1289: VecDuplicate - Creates a new vector of the same type as an existing vector.
1291: Collective on Vec
1293: Input Parameters:
1294: . v - a vector to mimic
1296: Output Parameter:
1297: . newv - location to put new vector
1299: Notes:
1300: VecDuplicate() does not copy the vector, but rather allocates storage
1301: for the new vector. Use VecCopy() to copy a vector.
1303: Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1304: vectors.
1306: Level: beginner
1308: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1309: @*/
1310: int VecDuplicate(Vec x,Vec *newv)
1311: {
1318: (*x->ops->duplicate)(x,newv);
1319: PetscObjectIncreaseState((PetscObject)*newv);
1320: return(0);
1321: }
1325: /*@C
1326: VecDestroy - Destroys a vector.
1328: Collective on Vec
1330: Input Parameters:
1331: . v - the vector
1333: Level: beginner
1335: .seealso: VecDuplicate(), VecDestroyVecs()
1336: @*/
1337: int VecDestroy(Vec v)
1338: {
1343: if (--v->refct > 0) return(0);
1344: /* destroy the internal part */
1345: if (v->ops->destroy) {
1346: (*v->ops->destroy)(v);
1347: }
1348: /* destroy the external/common part */
1349: if (v->mapping) {
1350: ISLocalToGlobalMappingDestroy(v->mapping);
1351: }
1352: if (v->bmapping) {
1353: ISLocalToGlobalMappingDestroy(v->bmapping);
1354: }
1355: if (v->map) {
1356: PetscMapDestroy(v->map);
1357: }
1358: PetscLogObjectDestroy(v);
1359: PetscHeaderDestroy(v);
1360: return(0);
1361: }
1365: /*@C
1366: VecDuplicateVecs - Creates several vectors of the same type as an existing vector.
1368: Collective on Vec
1370: Input Parameters:
1371: + m - the number of vectors to obtain
1372: - v - a vector to mimic
1374: Output Parameter:
1375: . V - location to put pointer to array of vectors
1377: Notes:
1378: Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1379: vector.
1381: Fortran Note:
1382: The Fortran interface is slightly different from that given below, it
1383: requires one to pass in V a Vec (integer) array of size at least m.
1384: See the Fortran chapter of the users manual and petsc/src/vec/examples for details.
1386: Level: intermediate
1388: .seealso: VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1389: @*/
1390: int VecDuplicateVecs(Vec v,int m,Vec *V[])
1391: {
1398: (*v->ops->duplicatevecs)(v, m,V);
1399: return(0);
1400: }
1404: /*@C
1405: VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().
1407: Collective on Vec
1409: Input Parameters:
1410: + vv - pointer to array of vector pointers
1411: - m - the number of vectors previously obtained
1413: Fortran Note:
1414: The Fortran interface is slightly different from that given below.
1415: See the Fortran chapter of the users manual and
1416: petsc/src/vec/examples for details.
1418: Level: intermediate
1420: .seealso: VecDuplicateVecs(), VecDestroyVecsF90()
1421: @*/
1422: int VecDestroyVecs(const Vec vv[],int m)
1423: {
1430: (*(*vv)->ops->destroyvecs)(vv,m);
1431: return(0);
1432: }
1437: /*@
1438: VecSetValues - Inserts or adds values into certain locations of a vector.
1440: Input Parameters:
1441: Not Collective
1443: + x - vector to insert in
1444: . ni - number of elements to add
1445: . ix - indices where to add
1446: . y - array of values
1447: - iora - either INSERT_VALUES or ADD_VALUES, where
1448: ADD_VALUES adds values to any existing entries, and
1449: INSERT_VALUES replaces existing entries with new values
1451: Notes:
1452: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1454: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1455: options cannot be mixed without intervening calls to the assembly
1456: routines.
1458: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1459: MUST be called after all calls to VecSetValues() have been completed.
1461: VecSetValues() uses 0-based indices in Fortran as well as in C.
1463: Negative indices may be passed in ix, these rows are
1464: simply ignored. This allows easily inserting element load matrices
1465: with homogeneous Dirchlet boundary conditions that you don't want represented
1466: in the vector.
1468: Level: beginner
1470: Concepts: vector^setting values
1472: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1473: VecSetValue(), VecSetValuesBlocked()
1474: @*/
1475: int VecSetValues(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1476: {
1484: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1485: (*x->ops->setvalues)(x,ni,ix,y,iora);
1486: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1487: PetscObjectIncreaseState((PetscObject)x);
1488: return(0);
1489: }
1493: /*@
1494: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
1496: Not Collective
1498: Input Parameters:
1499: + x - vector to insert in
1500: . ni - number of blocks to add
1501: . ix - indices where to add in block count, rather than element count
1502: . y - array of values
1503: - iora - either INSERT_VALUES or ADD_VALUES, where
1504: ADD_VALUES adds values to any existing entries, and
1505: INSERT_VALUES replaces existing entries with new values
1507: Notes:
1508: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
1509: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
1511: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1512: options cannot be mixed without intervening calls to the assembly
1513: routines.
1515: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1516: MUST be called after all calls to VecSetValuesBlocked() have been completed.
1518: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
1520: Negative indices may be passed in ix, these rows are
1521: simply ignored. This allows easily inserting element load matrices
1522: with homogeneous Dirchlet boundary conditions that you don't want represented
1523: in the vector.
1525: Level: intermediate
1527: Concepts: vector^setting values blocked
1529: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1530: VecSetValues()
1531: @*/
1532: int VecSetValuesBlocked(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1533: {
1541: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1542: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1543: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1544: PetscObjectIncreaseState((PetscObject)x);
1545: return(0);
1546: }
1550: /*@
1551: VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1552: by the routine VecSetValuesLocal() to allow users to insert vector entries
1553: using a local (per-processor) numbering.
1555: Collective on Vec
1557: Input Parameters:
1558: + x - vector
1559: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1561: Notes:
1562: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1564: Level: intermediate
1566: Concepts: vector^setting values with local numbering
1568: seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1569: VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1570: @*/
1571: int VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1572: {
1578: if (x->mapping) {
1579: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1580: }
1582: if (x->ops->setlocaltoglobalmapping) {
1583: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1584: } else {
1585: x->mapping = mapping;
1586: PetscObjectReference((PetscObject)mapping);
1587: }
1588: return(0);
1589: }
1593: /*@
1594: VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1595: by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1596: using a local (per-processor) numbering.
1598: Collective on Vec
1600: Input Parameters:
1601: + x - vector
1602: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1604: Notes:
1605: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1607: Level: intermediate
1609: Concepts: vector^setting values blocked with local numbering
1611: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1612: VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1613: @*/
1614: int VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1615: {
1621: if (x->bmapping) {
1622: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1623: }
1624: x->bmapping = mapping;
1625: PetscObjectReference((PetscObject)mapping);
1626: return(0);
1627: }
1631: /*@
1632: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1633: using a local ordering of the nodes.
1635: Not Collective
1637: Input Parameters:
1638: + x - vector to insert in
1639: . ni - number of elements to add
1640: . ix - indices where to add
1641: . y - array of values
1642: - iora - either INSERT_VALUES or ADD_VALUES, where
1643: ADD_VALUES adds values to any existing entries, and
1644: INSERT_VALUES replaces existing entries with new values
1646: Level: intermediate
1648: Notes:
1649: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1651: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1652: options cannot be mixed without intervening calls to the assembly
1653: routines.
1655: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1656: MUST be called after all calls to VecSetValuesLocal() have been completed.
1658: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
1660: Concepts: vector^setting values with local numbering
1662: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1663: VecSetValuesBlockedLocal()
1664: @*/
1665: int VecSetValuesLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1666: {
1667: int ierr,lixp[128],*lix = lixp;
1675: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1676: if (!x->ops->setvalueslocal) {
1677: if (!x->mapping) {
1678: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1679: }
1680: if (ni > 128) {
1681: PetscMalloc(ni*sizeof(int),&lix);
1682: }
1683: ISLocalToGlobalMappingApply(x->mapping,ni,(int*)ix,lix);
1684: (*x->ops->setvalues)(x,ni,lix,y,iora);
1685: if (ni > 128) {
1686: PetscFree(lix);
1687: }
1688: } else {
1689: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1690: }
1691: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1692: PetscObjectIncreaseState((PetscObject)x);
1693: return(0);
1694: }
1698: /*@
1699: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1700: using a local ordering of the nodes.
1702: Not Collective
1704: Input Parameters:
1705: + x - vector to insert in
1706: . ni - number of blocks to add
1707: . ix - indices where to add in block count, not element count
1708: . y - array of values
1709: - iora - either INSERT_VALUES or ADD_VALUES, where
1710: ADD_VALUES adds values to any existing entries, and
1711: INSERT_VALUES replaces existing entries with new values
1713: Level: intermediate
1715: Notes:
1716: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
1717: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
1719: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1720: options cannot be mixed without intervening calls to the assembly
1721: routines.
1723: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1724: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
1726: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
1729: Concepts: vector^setting values blocked with local numbering
1731: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
1732: VecSetLocalToGlobalMappingBlocked()
1733: @*/
1734: int VecSetValuesBlockedLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1735: {
1736: int ierr,lixp[128],*lix = lixp;
1743: if (!x->bmapping) {
1744: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1745: }
1746: if (ni > 128) {
1747: PetscMalloc(ni*sizeof(int),&lix);
1748: }
1750: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1751: ISLocalToGlobalMappingApply(x->bmapping,ni,(int*)ix,lix);
1752: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1753: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1754: if (ni > 128) {
1755: PetscFree(lix);
1756: }
1757: PetscObjectIncreaseState((PetscObject)x);
1758: return(0);
1759: }
1763: /*@
1764: VecAssemblyBegin - Begins assembling the vector. This routine should
1765: be called after completing all calls to VecSetValues().
1767: Collective on Vec
1769: Input Parameter:
1770: . vec - the vector
1772: Level: beginner
1774: Concepts: assembly^vectors
1776: .seealso: VecAssemblyEnd(), VecSetValues()
1777: @*/
1778: int VecAssemblyBegin(Vec vec)
1779: {
1780: int ierr;
1781: PetscTruth flg;
1787: PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1788: if (flg) {
1789: VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1790: }
1792: PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1793: if (vec->ops->assemblybegin) {
1794: (*vec->ops->assemblybegin)(vec);
1795: }
1796: PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1797: PetscObjectIncreaseState((PetscObject)vec);
1798: return(0);
1799: }
1803: /*@
1804: VecAssemblyEnd - Completes assembling the vector. This routine should
1805: be called after VecAssemblyBegin().
1807: Collective on Vec
1809: Input Parameter:
1810: . vec - the vector
1812: Options Database Keys:
1813: + -vec_view - Prints vector in ASCII format
1814: . -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
1815: . -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
1816: . -vec_view_draw - Activates vector viewing using drawing tools
1817: . -display <name> - Sets display name (default is host)
1818: . -draw_pause <sec> - Sets number of seconds to pause after display
1819: . -vec_view_socket - Activates vector viewing using a socket
1820: - -vec_view_ams - Activates vector viewing using the ALICE Memory Snooper (AMS)
1821:
1822: Level: beginner
1824: .seealso: VecAssemblyBegin(), VecSetValues()
1825: @*/
1826: int VecAssemblyEnd(Vec vec)
1827: {
1828: int ierr;
1829: PetscTruth flg;
1833: PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
1835: if (vec->ops->assemblyend) {
1836: (*vec->ops->assemblyend)(vec);
1837: }
1838: PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
1839: PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
1840: PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
1841: if (flg) {
1842: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1843: }
1844: PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
1845: if (flg) {
1846: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
1847: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1848: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
1849: }
1850: #if defined(PETSC_HAVE_MATLAB) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
1851: PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
1852: if (flg) {
1853: VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
1854: }
1855: #endif
1856: PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
1857: if (flg) {
1858: VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
1859: PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
1860: }
1861: PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
1862: if (flg) {
1863: VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
1864: PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
1865: }
1866: #if defined(PETSC_HAVE_AMS)
1867: PetscOptionsName("-vec_view_ams","View vector using AMS","VecView",&flg);
1868: if (flg) {
1869: VecView(vec,PETSC_VIEWER_AMS_(vec->comm));
1870: }
1871: #endif
1872: PetscOptionsEnd();
1873: /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
1874: /* hence they should not be inside the above PetscOptionsBegin/End block. */
1875: PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
1876: if (flg) {
1877: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1878: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1879: }
1880: PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
1881: if (flg) {
1882: PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
1883: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1884: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1885: }
1886: return(0);
1887: }
1892: /*@C
1893: VecMTDot - Computes indefinite vector multiple dot products.
1894: That is, it does NOT use the complex conjugate.
1896: Collective on Vec
1898: Input Parameters:
1899: + nv - number of vectors
1900: . x - one vector
1901: - y - array of vectors. Note that vectors are pointers
1903: Output Parameter:
1904: . val - array of the dot products
1906: Notes for Users of Complex Numbers:
1907: For complex vectors, VecMTDot() computes the indefinite form
1908: $ val = (x,y) = y^T x,
1909: where y^T denotes the transpose of y.
1911: Use VecMDot() for the inner product
1912: $ val = (x,y) = y^H x,
1913: where y^H denotes the conjugate transpose of y.
1915: Level: intermediate
1917: Concepts: inner product^multiple
1918: Concepts: vector^multiple inner products
1920: .seealso: VecMDot(), VecTDot()
1921: @*/
1922: int VecMTDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1923: {
1934: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1935: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1937: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1938: (*x->ops->mtdot)(nv,x,y,val);
1939: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1940: return(0);
1941: }
1945: /*@C
1946: VecMDot - Computes vector multiple dot products.
1948: Collective on Vec
1950: Input Parameters:
1951: + nv - number of vectors
1952: . x - one vector
1953: - y - array of vectors.
1955: Output Parameter:
1956: . val - array of the dot products
1958: Notes for Users of Complex Numbers:
1959: For complex vectors, VecMDot() computes
1960: $ val = (x,y) = y^H x,
1961: where y^H denotes the conjugate transpose of y.
1963: Use VecMTDot() for the indefinite form
1964: $ val = (x,y) = y^T x,
1965: where y^T denotes the transpose of y.
1967: Level: intermediate
1969: Concepts: inner product^multiple
1970: Concepts: vector^multiple inner products
1972: .seealso: VecMTDot(), VecDot()
1973: @*/
1974: int VecMDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1975: {
1986: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1987: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1989: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1990: (*x->ops->mdot)(nv,x,y,val);
1991: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
1992: return(0);
1993: }
1997: /*@C
1998: VecMAXPY - Computes y = y + sum alpha[j] x[j]
2000: Collective on Vec
2002: Input Parameters:
2003: + nv - number of scalars and x-vectors
2004: . alpha - array of scalars
2005: . y - one vector
2006: - x - array of vectors
2008: Level: intermediate
2010: Concepts: BLAS
2012: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2013: @*/
2014: int VecMAXPY(int nv,const PetscScalar *alpha,Vec y,Vec *x)
2015: {
2026: if (y->N != (*x)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2027: if (y->n != (*x)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
2029: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2030: (*y->ops->maxpy)(nv,alpha,y,x);
2031: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2032: PetscObjectIncreaseState((PetscObject)y);
2033: return(0);
2034: }
2036: /*MC
2037: VecGetArray - Returns a pointer to a contiguous array that contains this
2038: processor's portion of the vector data. For the standard PETSc
2039: vectors, VecGetArray() returns a pointer to the local data array and
2040: does not use any copies. If the underlying vector data is not stored
2041: in a contiquous array this routine will copy the data to a contiquous
2042: array and return a pointer to that. You MUST call VecRestoreArray()
2043: when you no longer need access to the array.
2045: Not Collective
2047: Input Parameter:
2048: . x - the vector
2050: Output Parameter:
2051: . a - location to put pointer to the array
2053: Fortran Note:
2054: This routine is used differently from Fortran 77
2055: $ Vec x
2056: $ PetscScalar x_array(1)
2057: $ PetscOffset i_x
2058: $ int ierr
2059: $ call VecGetArray(x,x_array,i_x,ierr)
2060: $
2061: $ Access first local entry in vector with
2062: $ value = x_array(i_x + 1)
2063: $
2064: $ ...... other code
2065: $ call VecRestoreArray(x,x_array,i_x,ierr)
2066: For Fortran 90 see VecGetArrayF90()
2068: See the Fortran chapter of the users manual and
2069: petsc/src/snes/examples/tutorials/ex5f.F for details.
2071: Level: beginner
2073: Concepts: vector^accessing local values
2075: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2076: M*/
2079: int VecGetArray_Private(Vec x,PetscScalar *a[])
2080: {
2087: (*x->ops->getarray)(x,a);
2088: return(0);
2089: }
2094: /*@C
2095: VecGetArrays - Returns a pointer to the arrays in a set of vectors
2096: that were created by a call to VecDuplicateVecs(). You MUST call
2097: VecRestoreArrays() when you no longer need access to the array.
2099: Not Collective
2101: Input Parameter:
2102: + x - the vectors
2103: - n - the number of vectors
2105: Output Parameter:
2106: . a - location to put pointer to the array
2108: Fortran Note:
2109: This routine is not supported in Fortran.
2111: Level: intermediate
2113: .seealso: VecGetArray(), VecRestoreArrays()
2114: @*/
2115: int VecGetArrays(const Vec x[],int n,PetscScalar **a[])
2116: {
2117: int i,ierr;
2118: PetscScalar **q;
2124: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %d",n);
2125: PetscMalloc(n*sizeof(PetscScalar*),&q);
2126: for (i=0; i<n; ++i) {
2127: VecGetArray(x[i],&q[i]);
2128: }
2129: *a = q;
2130: return(0);
2131: }
2135: /*@C
2136: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2137: has been called.
2139: Not Collective
2141: Input Parameters:
2142: + x - the vector
2143: . n - the number of vectors
2144: - a - location of pointer to arrays obtained from VecGetArrays()
2146: Notes:
2147: For regular PETSc vectors this routine does not involve any copies. For
2148: any special vectors that do not store local vector data in a contiguous
2149: array, this routine will copy the data back into the underlying
2150: vector data structure from the arrays obtained with VecGetArrays().
2152: Fortran Note:
2153: This routine is not supported in Fortran.
2155: Level: intermediate
2157: .seealso: VecGetArrays(), VecRestoreArray()
2158: @*/
2159: int VecRestoreArrays(const Vec x[],int n,PetscScalar **a[])
2160: {
2161: int i,ierr;
2162: PetscScalar **q = *a;
2169: for(i=0;i<n;++i) {
2170: VecRestoreArray(x[i],&q[i]);
2171: }
2172: PetscFree(q);
2173: return(0);
2174: }
2176: /*MC
2177: VecRestoreArray - Restores a vector after VecGetArray() has been called.
2179: Not Collective
2181: Input Parameters:
2182: + x - the vector
2183: - a - location of pointer to array obtained from VecGetArray()
2185: Level: beginner
2187: Notes:
2188: For regular PETSc vectors this routine does not involve any copies. For
2189: any special vectors that do not store local vector data in a contiguous
2190: array, this routine will copy the data back into the underlying
2191: vector data structure from the array obtained with VecGetArray().
2193: This routine actually zeros out the a pointer. This is to prevent accidental
2194: us of the array after it has been restored. If you pass null for a it will
2195: not zero the array pointer a.
2197: Fortran Note:
2198: This routine is used differently from Fortran 77
2199: $ Vec x
2200: $ PetscScalar x_array(1)
2201: $ PetscOffset i_x
2202: $ int ierr
2203: $ call VecGetArray(x,x_array,i_x,ierr)
2204: $
2205: $ Access first local entry in vector with
2206: $ value = x_array(i_x + 1)
2207: $
2208: $ ...... other code
2209: $ call VecRestoreArray(x,x_array,i_x,ierr)
2211: See the Fortran chapter of the users manual and
2212: petsc/src/snes/examples/tutorials/ex5f.F for details.
2213: For Fortran 90 see VecRestoreArrayF90()
2215: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2216: M*/
2219: int VecRestoreArray_Private(Vec x,PetscScalar *a[])
2220: {
2227: #if defined(PETSC_USE_BOPT_g)
2228: CHKMEMQ;
2229: #endif
2230: if (x->ops->restorearray) {
2231: (*x->ops->restorearray)(x,a);
2232: }
2233: PetscObjectIncreaseState((PetscObject)x);
2234: return(0);
2235: }
2237: #undef __FUNCT__
2239: /*@
2240: VecViewFromOptions - This function visualizes the vector based upon user options.
2242: Collective on Vec
2244: Input Parameters:
2245: . vec - The vector
2246: . title - The title
2248: Level: intermediate
2250: .keywords: Vec, view, options, database
2251: .seealso: VecSetFromOptions(), VecView()
2252: @*/
2253: int VecViewFromOptions(Vec vec, char *title)
2254: {
2255: PetscViewer viewer;
2256: PetscDraw draw;
2257: PetscTruth opt;
2258: char *titleStr;
2259: char typeName[1024];
2260: char fileName[PETSC_MAX_PATH_LEN];
2261: int len;
2262: int ierr;
2265: PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2266: if (opt == PETSC_TRUE) {
2267: PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2268: PetscStrlen(typeName, &len);
2269: if (len > 0) {
2270: PetscViewerCreate(vec->comm, &viewer);
2271: PetscViewerSetType(viewer, typeName);
2272: PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2273: if (opt == PETSC_TRUE) {
2274: PetscViewerSetFilename(viewer, fileName);
2275: } else {
2276: PetscViewerSetFilename(viewer, vec->name);
2277: }
2278: VecView(vec, viewer);
2279: PetscViewerFlush(viewer);
2280: PetscViewerDestroy(viewer);
2281: } else {
2282: VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2283: }
2284: }
2285: PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2286: if (opt == PETSC_TRUE) {
2287: PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2288: PetscViewerDrawGetDraw(viewer, 0, &draw);
2289: if (title != PETSC_NULL) {
2290: titleStr = title;
2291: } else {
2292: PetscObjectName((PetscObject) vec); CHKERRQ(ierr) ;
2293: titleStr = vec->name;
2294: }
2295: PetscDrawSetTitle(draw, titleStr);
2296: VecView(vec, viewer);
2297: PetscViewerFlush(viewer);
2298: PetscDrawPause(draw);
2299: PetscViewerDestroy(viewer);
2300: }
2301: return(0);
2302: }
2306: /*@C
2307: VecView - Views a vector object.
2309: Collective on Vec
2311: Input Parameters:
2312: + v - the vector
2313: - viewer - an optional visualization context
2315: Notes:
2316: The available visualization contexts include
2317: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
2318: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2319: output where only the first processor opens
2320: the file. All other processors send their
2321: data to the first processor to print.
2323: You can change the format the vector is printed using the
2324: option PetscViewerSetFormat().
2326: The user can open alternative visualization contexts with
2327: + PetscViewerASCIIOpen() - Outputs vector to a specified file
2328: . PetscViewerBinaryOpen() - Outputs vector in binary to a
2329: specified file; corresponding input uses VecLoad()
2330: . PetscViewerDrawOpen() - Outputs vector to an X window display
2331: - PetscViewerSocketOpen() - Outputs vector to Socket viewer
2333: The user can call PetscViewerSetFormat() to specify the output
2334: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2335: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
2336: + PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2337: . PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2338: . PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2339: - PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
2340: format common among all vector types
2342: Level: beginner
2344: Concepts: vector^printing
2345: Concepts: vector^saving to disk
2347: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2348: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2349: PetscRealView(), PetscScalarView(), PetscIntView()
2350: @*/
2351: int VecView(Vec vec,PetscViewer viewer)
2352: {
2353: int ierr;
2354: PetscViewerFormat format;
2359: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
2362: if (vec->stash.n || vec->bstash.n) SETERRQ(1,"Must call VecAssemblyBegin/End() before viewing this vector");
2364: /*
2365: Check if default viewer has been overridden, but user request it anyways
2366: */
2367: PetscViewerGetFormat(viewer,&format);
2368: if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2369: PetscViewerPopFormat(viewer);
2370: (*vec->ops->viewnative)(vec,viewer);
2371: PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2372: } else {
2373: (*vec->ops->view)(vec,viewer);
2374: }
2375: return(0);
2376: }
2380: /*@
2381: VecGetSize - Returns the global number of elements of the vector.
2383: Not Collective
2385: Input Parameter:
2386: . x - the vector
2388: Output Parameters:
2389: . size - the global length of the vector
2391: Level: beginner
2393: Concepts: vector^local size
2395: .seealso: VecGetLocalSize()
2396: @*/
2397: int VecGetSize(Vec x,int *size)
2398: {
2405: (*x->ops->getsize)(x,size);
2406: return(0);
2407: }
2411: /*@
2412: VecGetLocalSize - Returns the number of elements of the vector stored
2413: in local memory. This routine may be implementation dependent, so use
2414: with care.
2416: Not Collective
2418: Input Parameter:
2419: . x - the vector
2421: Output Parameter:
2422: . size - the length of the local piece of the vector
2424: Level: beginner
2426: Concepts: vector^size
2428: .seealso: VecGetSize()
2429: @*/
2430: int VecGetLocalSize(Vec x,int *size)
2431: {
2438: (*x->ops->getlocalsize)(x,size);
2439: return(0);
2440: }
2444: /*@C
2445: VecGetOwnershipRange - Returns the range of indices owned by
2446: this processor, assuming that the vectors are laid out with the
2447: first n1 elements on the first processor, next n2 elements on the
2448: second, etc. For certain parallel layouts this range may not be
2449: well defined.
2451: Not Collective
2453: Input Parameter:
2454: . x - the vector
2456: Output Parameters:
2457: + low - the first local element, pass in PETSC_NULL if not interested
2458: - high - one more than the last local element, pass in PETSC_NULL if not interested
2460: Note:
2461: The high argument is one more than the last element stored locally.
2463: Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL
2465: Level: beginner
2467: Concepts: ownership^of vectors
2468: Concepts: vector^ownership of elements
2470: @*/
2471: int VecGetOwnershipRange(Vec x,int *low,int *high)
2472: {
2473: int ierr;
2480: PetscMapGetLocalRange(x->map,low,high);
2481: return(0);
2482: }
2486: /*@C
2487: VecGetPetscMap - Returns the map associated with the vector
2489: Not Collective
2491: Input Parameter:
2492: . x - the vector
2494: Output Parameters:
2495: . map - the map
2497: Level: developer
2499: @*/
2500: int VecGetPetscMap(Vec x,PetscMap *map)
2501: {
2506: *map = x->map;
2507: return(0);
2508: }
2512: /*@
2513: VecSetOption - Sets an option for controling a vector's behavior.
2515: Collective on Vec
2517: Input Parameter:
2518: + x - the vector
2519: - op - the option
2521: Supported Options:
2522: + VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
2523: entries destined to be stored on a seperate processor. This can be used
2524: to eliminate the global reduction in the VecAssemblyXXXX() if you know
2525: that you have only used VecSetValues() to set local elements
2526: - VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.
2528: Level: intermediate
2530: @*/
2531: int VecSetOption(Vec x,VecOption op)
2532: {
2538: if (x->ops->setoption) {
2539: (*x->ops->setoption)(x,op);
2540: }
2541: return(0);
2542: }
2546: /* Default routines for obtaining and releasing; */
2547: /* may be used by any implementation */
2548: int VecDuplicateVecs_Default(Vec w,int m,Vec *V[])
2549: {
2550: int i,ierr;
2555: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2556: PetscMalloc(m*sizeof(Vec*),V);
2557: for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2558: return(0);
2559: }
2563: int VecDestroyVecs_Default(const Vec v[], int m)
2564: {
2565: int i,ierr;
2569: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2570: for (i=0; i<m; i++) {VecDestroy(v[i]);}
2571: PetscFree((Vec*)v);
2572: return(0);
2573: }
2577: /*@
2578: VecPlaceArray - Allows one to replace the array in a vector with an
2579: array provided by the user. This is useful to avoid copying an array
2580: into a vector.
2582: Not Collective
2584: Input Parameters:
2585: + vec - the vector
2586: - array - the array
2588: Notes:
2589: You can return to the original array with a call to VecResetArray()
2591: Level: developer
2593: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
2595: @*/
2596: int VecPlaceArray(Vec vec,const PetscScalar array[])
2597: {
2604: if (vec->ops->placearray) {
2605: (*vec->ops->placearray)(vec,array);
2606: } else {
2607: SETERRQ(1,"Cannot place array in this type of vector");
2608: }
2609: PetscObjectIncreaseState((PetscObject)vec);
2610: return(0);
2611: }
2615: /*@
2616: VecResetArray - Resets a vector to use its default memory. Call this
2617: after the use of VecPlaceArray().
2619: Not Collective
2621: Input Parameters:
2622: . vec - the vector
2624: Level: developer
2626: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()
2628: @*/
2629: int VecResetArray(Vec vec)
2630: {
2636: if (vec->ops->resetarray) {
2637: (*vec->ops->resetarray)(vec);
2638: } else {
2639: SETERRQ(1,"Cannot reset array in this type of vector");
2640: }
2641: PetscObjectIncreaseState((PetscObject)vec);
2642: return(0);
2643: }
2647: /*@C
2648: VecReplaceArray - Allows one to replace the array in a vector with an
2649: array provided by the user. This is useful to avoid copying an array
2650: into a vector.
2652: Not Collective
2654: Input Parameters:
2655: + vec - the vector
2656: - array - the array
2658: Notes:
2659: This permanently replaces the array and frees the memory associated
2660: with the old array.
2662: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2663: freed by the user. It will be freed when the vector is destroy.
2665: Not supported from Fortran
2667: Level: developer
2669: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
2671: @*/
2672: int VecReplaceArray(Vec vec,const PetscScalar array[])
2673: {
2679: if (vec->ops->replacearray) {
2680: (*vec->ops->replacearray)(vec,array);
2681: } else {
2682: SETERRQ(1,"Cannot replace array in this type of vector");
2683: }
2684: PetscObjectIncreaseState((PetscObject)vec);
2685: return(0);
2686: }
2688: /*MC
2689: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2690: and makes them accessible via a Fortran90 pointer.
2692: Synopsis:
2693: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
2695: Collective on Vec
2697: Input Parameters:
2698: + x - a vector to mimic
2699: - n - the number of vectors to obtain
2701: Output Parameters:
2702: + y - Fortran90 pointer to the array of vectors
2703: - ierr - error code
2705: Example of Usage:
2706: .vb
2707: Vec x
2708: Vec, pointer :: y(:)
2709: ....
2710: call VecDuplicateVecsF90(x,2,y,ierr)
2711: call VecSet(alpha,y(2),ierr)
2712: call VecSet(alpha,y(2),ierr)
2713: ....
2714: call VecDestroyVecsF90(y,2,ierr)
2715: .ve
2717: Notes:
2718: Not yet supported for all F90 compilers
2720: Use VecDestroyVecsF90() to free the space.
2722: Level: beginner
2724: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
2726: M*/
2728: /*MC
2729: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2730: VecGetArrayF90().
2732: Synopsis:
2733: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2735: Not collective
2737: Input Parameters:
2738: + x - vector
2739: - xx_v - the Fortran90 pointer to the array
2741: Output Parameter:
2742: . ierr - error code
2744: Example of Usage:
2745: .vb
2746: PetscScalar, pointer :: xx_v(:)
2747: ....
2748: call VecGetArrayF90(x,xx_v,ierr)
2749: a = xx_v(3)
2750: call VecRestoreArrayF90(x,xx_v,ierr)
2751: .ve
2752:
2753: Notes:
2754: Not yet supported for all F90 compilers
2756: Level: beginner
2758: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray()
2760: M*/
2762: /*MC
2763: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
2765: Synopsis:
2766: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
2768: Input Parameters:
2769: + x - pointer to array of vector pointers
2770: - n - the number of vectors previously obtained
2772: Output Parameter:
2773: . ierr - error code
2775: Notes:
2776: Not yet supported for all F90 compilers
2778: Level: beginner
2780: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
2782: M*/
2784: /*MC
2785: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2786: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2787: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
2788: when you no longer need access to the array.
2790: Synopsis:
2791: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2793: Not Collective
2795: Input Parameter:
2796: . x - vector
2798: Output Parameters:
2799: + xx_v - the Fortran90 pointer to the array
2800: - ierr - error code
2802: Example of Usage:
2803: .vb
2804: PetscScalar, pointer :: xx_v(:)
2805: ....
2806: call VecGetArrayF90(x,xx_v,ierr)
2807: a = xx_v(3)
2808: call VecRestoreArrayF90(x,xx_v,ierr)
2809: .ve
2811: Notes:
2812: Not yet supported for all F90 compilers
2814: Level: beginner
2816: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()
2818: M*/
2822: /*@C
2823: VecLoadIntoVector - Loads a vector that has been stored in binary format
2824: with VecView().
2826: Collective on PetscViewer
2828: Input Parameters:
2829: + viewer - binary file viewer, obtained from PetscViewerBinaryOpen()
2830: - vec - vector to contain files values (must be of correct length)
2832: Level: intermediate
2834: Notes:
2835: The input file must contain the full global vector, as
2836: written by the routine VecView().
2838: Use VecLoad() to create the vector as the values are read in
2840: Notes for advanced users:
2841: Most users should not need to know the details of the binary storage
2842: format, since VecLoad() and VecView() completely hide these details.
2843: But for anyone who's interested, the standard binary matrix storage
2844: format is
2845: .vb
2846: int VEC_FILE_COOKIE
2847: int number of rows
2848: PetscScalar *values of all nonzeros
2849: .ve
2851: Note for Cray users, the int's stored in the binary file are 32 bit
2852: integers; not 64 as they are represented in the memory, so if you
2853: write your own routines to read/write these binary files from the Cray
2854: you need to adjust the integer sizes that you read in, see
2855: PetscReadBinary() and PetscWriteBinary() to see how this may be
2856: done.
2858: In addition, PETSc automatically does the byte swapping for
2859: machines that store the bytes reversed, e.g. DEC alpha, freebsd,
2860: linux, nt and the paragon; thus if you write your own binary
2861: read/write routines you have to swap the bytes; see PetscReadBinary()
2862: and PetscWriteBinary() to see how this may be done.
2864: Concepts: vector^loading from file
2866: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
2867: @*/
2868: int VecLoadIntoVector(PetscViewer viewer,Vec vec)
2869: {
2876: if (!vec->ops->loadintovector) {
2877: SETERRQ(1,"Vector does not support load");
2878: }
2879: (*vec->ops->loadintovector)(viewer,vec);
2880: PetscObjectIncreaseState((PetscObject)vec);
2881: return(0);
2882: }
2886: /*@
2887: VecReciprocal - Replaces each component of a vector by its reciprocal.
2889: Collective on Vec
2891: Input Parameter:
2892: . v - the vector
2894: Output Parameter:
2895: . v - the vector reciprocal
2897: Level: intermediate
2899: Concepts: vector^reciprocal
2901: @*/
2902: int VecReciprocal(Vec vec)
2903: {
2904: int ierr;
2909: if (!vec->ops->reciprocal) {
2910: SETERRQ(1,"Vector does not support reciprocal operation");
2911: }
2912: (*vec->ops->reciprocal)(vec);
2913: PetscObjectIncreaseState((PetscObject)vec);
2914: return(0);
2915: }
2919: int VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2920: {
2923: /* save the native version of the viewer */
2924: if (op == VECOP_VIEW && !vec->ops->viewnative) {
2925: vec->ops->viewnative = vec->ops->view;
2926: }
2927: (((void(**)(void))vec->ops)[(int)op]) = f;
2928: return(0);
2929: }
2933: /*@
2934: VecSetStashInitialSize - sets the sizes of the vec-stash, that is
2935: used during the assembly process to store values that belong to
2936: other processors.
2938: Collective on Vec
2940: Input Parameters:
2941: + vec - the vector
2942: . size - the initial size of the stash.
2943: - bsize - the initial size of the block-stash(if used).
2945: Options Database Keys:
2946: + -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2947: - -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
2949: Level: intermediate
2951: Notes:
2952: The block-stash is used for values set with VecSetValuesBlocked() while
2953: the stash is used for values set with VecSetValues()
2955: Run with the option -log_info and look for output of the form
2956: VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2957: to determine the appropriate value, MM, to use for size and
2958: VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2959: to determine the value, BMM to use for bsize
2961: Concepts: vector^stash
2962: Concepts: stash^vector
2964: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()
2966: @*/
2967: int VecSetStashInitialSize(Vec vec,int size,int bsize)
2968: {
2973: VecStashSetInitialSize_Private(&vec->stash,size);
2974: VecStashSetInitialSize_Private(&vec->bstash,bsize);
2975: return(0);
2976: }
2980: /*@
2981: VecStashView - Prints the entries in the vector stash and block stash.
2983: Collective on Vec
2985: Input Parameters:
2986: + vec - the vector
2987: - viewer - the viewer
2989: Level: advanced
2991: Concepts: vector^stash
2992: Concepts: stash^vector
2994: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()
2996: @*/
2997: int VecStashView(Vec v,PetscViewer viewer)
2998: {
2999: int ierr,rank,i,j;
3000: PetscTruth match;
3001: VecStash *s;
3002: PetscScalar val;
3009: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3010: if (!match) SETERRQ1(1,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3011: PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3012: MPI_Comm_rank(v->comm,&rank);
3013: s = &v->bstash;
3015: /* print block stash */
3016: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %d block size %d\n",rank,s->n,s->bs);
3017: for (i=0; i<s->n; i++) {
3018: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d ",rank,s->idx[i]);
3019: for (j=0; j<s->bs; j++) {
3020: val = s->array[i*s->bs+j];
3021: #if defined(PETSC_USE_COMPLEX)
3022: PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3023: #else
3024: PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3025: #endif
3026: }
3027: PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3028: }
3029: PetscViewerFlush(viewer);
3031: s = &v->stash;
3033: /* print basic stash */
3034: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %d\n",rank,s->n);
3035: for (i=0; i<s->n; i++) {
3036: val = s->array[i];
3037: #if defined(PETSC_USE_COMPLEX)
3038: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3039: #else
3040: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d %18.16e\n",rank,s->idx[i],val);
3041: #endif
3042: }
3043: PetscViewerFlush(viewer);
3045: PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3046: return(0);
3047: }
3051: /*@C
3052: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
3053: processor's portion of the vector data. You MUST call VecRestoreArray2d()
3054: when you no longer need access to the array.
3056: Not Collective
3058: Input Parameter:
3059: + x - the vector
3060: . m - first dimension of two dimensional array
3061: . n - second dimension of two dimensional array
3062: . mstart - first index you will use in first coordinate direction (often 0)
3063: - nstart - first index in the second coordinate direction (often 0)
3065: Output Parameter:
3066: . a - location to put pointer to the array
3068: Level: beginner
3070: Notes:
3071: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3072: obtained from the corner indices obtained from DAGetGhostCorners() while for
3073: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3074: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3075:
3076: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3078: Concepts: vector^accessing local values as 2d array
3080: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3081: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3082: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3083: @*/
3084: int VecGetArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
3085: {
3086: int i,ierr,N;
3087: PetscScalar *aa;
3093: VecGetLocalSize(x,&N);
3094: if (m*n != N) SETERRQ3(1,"Local array size %d does not match 2d array dimensions %d by %d",N,m,n);
3095: VecGetArray(x,&aa);
3097: PetscMalloc(m*sizeof(PetscScalar*),a);
3098: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3099: *a -= mstart;
3100: return(0);
3101: }
3105: /*@C
3106: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
3108: Not Collective
3110: Input Parameters:
3111: + x - the vector
3112: . m - first dimension of two dimensional array
3113: . n - second dimension of the two dimensional array
3114: . mstart - first index you will use in first coordinate direction (often 0)
3115: . nstart - first index in the second coordinate direction (often 0)
3116: - a - location of pointer to array obtained from VecGetArray2d()
3118: Level: beginner
3120: Notes:
3121: For regular PETSc vectors this routine does not involve any copies. For
3122: any special vectors that do not store local vector data in a contiguous
3123: array, this routine will copy the data back into the underlying
3124: vector data structure from the array obtained with VecGetArray().
3126: This routine actually zeros out the a pointer.
3128: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3129: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3130: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3131: @*/
3132: int VecRestoreArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
3133: {
3140: PetscFree(*a + mstart);
3141: VecRestoreArray(x,PETSC_NULL);
3142: return(0);
3143: }
3147: /*@C
3148: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
3149: processor's portion of the vector data. You MUST call VecRestoreArray1d()
3150: when you no longer need access to the array.
3152: Not Collective
3154: Input Parameter:
3155: + x - the vector
3156: . m - first dimension of two dimensional array
3157: - mstart - first index you will use in first coordinate direction (often 0)
3159: Output Parameter:
3160: . a - location to put pointer to the array
3162: Level: beginner
3164: Notes:
3165: For a vector obtained from DACreateLocalVector() mstart are likely
3166: obtained from the corner indices obtained from DAGetGhostCorners() while for
3167: DACreateGlobalVector() they are the corner indices from DAGetCorners().
3168:
3169: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3171: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3172: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3173: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3174: @*/
3175: int VecGetArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3176: {
3177: int ierr,N;
3183: VecGetLocalSize(x,&N);
3184: if (m != N) SETERRQ2(1,"Local array size %d does not match 1d array dimensions %d",N,m);
3185: VecGetArray(x,a);
3186: *a -= mstart;
3187: return(0);
3188: }
3192: /*@C
3193: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
3195: Not Collective
3197: Input Parameters:
3198: + x - the vector
3199: . m - first dimension of two dimensional array
3200: . mstart - first index you will use in first coordinate direction (often 0)
3201: - a - location of pointer to array obtained from VecGetArray21()
3203: Level: beginner
3205: Notes:
3206: For regular PETSc vectors this routine does not involve any copies. For
3207: any special vectors that do not store local vector data in a contiguous
3208: array, this routine will copy the data back into the underlying
3209: vector data structure from the array obtained with VecGetArray1d().
3211: This routine actually zeros out the a pointer.
3213: Concepts: vector^accessing local values as 1d array
3215: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3216: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3217: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3218: @*/
3219: int VecRestoreArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3220: {
3226: VecRestoreArray(x,PETSC_NULL);
3227: return(0);
3228: }
3232: /*@C
3233: VecConjugate - Conjugates a vector.
3235: Collective on Vec
3237: Input Parameters:
3238: . x - the vector
3240: Level: intermediate
3242: Concepts: vector^conjugate
3244: @*/
3245: int VecConjugate(Vec x)
3246: {
3247: #ifdef PETSC_USE_COMPLEX
3253: (*x->ops->conjugate)(x);
3254: /* we need to copy norms here */
3255: PetscObjectIncreaseState((PetscObject)x);
3256: return(0);
3257: #else
3258: return(0);
3259: #endif
3260: }
3264: /*@C
3265: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
3266: processor's portion of the vector data. You MUST call VecRestoreArray3d()
3267: when you no longer need access to the array.
3269: Not Collective
3271: Input Parameter:
3272: + x - the vector
3273: . m - first dimension of three dimensional array
3274: . n - second dimension of three dimensional array
3275: . p - third dimension of three dimensional array
3276: . mstart - first index you will use in first coordinate direction (often 0)
3277: . nstart - first index in the second coordinate direction (often 0)
3278: - pstart - first index in the third coordinate direction (often 0)
3280: Output Parameter:
3281: . a - location to put pointer to the array
3283: Level: beginner
3285: Notes:
3286: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3287: obtained from the corner indices obtained from DAGetGhostCorners() while for
3288: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3289: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3290:
3291: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3293: Concepts: vector^accessing local values as 3d array
3295: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3296: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3297: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3298: @*/
3299: int VecGetArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3300: {
3301: int i,ierr,N,j;
3302: PetscScalar *aa,**b;
3308: VecGetLocalSize(x,&N);
3309: 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);
3310: VecGetArray(x,&aa);
3312: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3313: b = (PetscScalar **)((*a) + m);
3314: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3315: for (i=0; i<m; i++) {
3316: for (j=0; j<n; j++) {
3317: b[i*n+j] = aa + i*n*p + j*p - pstart;
3318: }
3319: }
3320: *a -= mstart;
3321: return(0);
3322: }
3326: /*@C
3327: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
3329: Not Collective
3331: Input Parameters:
3332: + x - the vector
3333: . m - first dimension of three dimensional array
3334: . n - second dimension of the three dimensional array
3335: . p - third dimension of the three dimensional array
3336: . mstart - first index you will use in first coordinate direction (often 0)
3337: . nstart - first index in the second coordinate direction (often 0)
3338: . pstart - first index in the third coordinate direction (often 0)
3339: - a - location of pointer to array obtained from VecGetArray3d()
3341: Level: beginner
3343: Notes:
3344: For regular PETSc vectors this routine does not involve any copies. For
3345: any special vectors that do not store local vector data in a contiguous
3346: array, this routine will copy the data back into the underlying
3347: vector data structure from the array obtained with VecGetArray().
3349: This routine actually zeros out the a pointer.
3351: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3352: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3353: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3354: @*/
3355: int VecRestoreArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3356: {
3363: PetscFree(*a + mstart);
3364: VecRestoreArray(x,PETSC_NULL);
3365: return(0);
3366: }