Actual source code: vector.c
1: /*
2: Provides the interface functions for all vector operations.
3: These are the vector functions the user calls.
4: */
5: #include vecimpl.h
7: /* Logging support */
8: PetscCookie VEC_COOKIE = 0;
9: PetscEvent VEC_View = 0, VEC_Max = 0, VEC_Min = 0, VEC_DotBarrier = 0, VEC_Dot = 0, VEC_MDotBarrier = 0, VEC_MDot = 0, VEC_TDot = 0;
10: PetscEvent VEC_Norm = 0, VEC_Normalize = 0, VEC_Scale = 0, VEC_Copy = 0, VEC_Set = 0, VEC_AXPY = 0, VEC_AYPX = 0, VEC_WAXPY = 0;
11: PetscEvent VEC_MTDot = 0, VEC_NormBarrier = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
12: PetscEvent VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0;
13: PetscEvent VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;
15: /* ugly globals for VecSetValue() and VecSetValueLocal() */
16: PetscInt 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 PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
36: {
37: PetscTruth opt;
38: const char *defaultType;
39: char typeName[256];
40: PetscMPIInt size;
44: if (vec->type_name) {
45: defaultType = vec->type_name;
46: } else {
47: MPI_Comm_size(vec->comm, &size);
48: if (size > 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: if (opt) {
60: VecSetType(vec, typeName);
61: } else {
62: VecSetType(vec, defaultType);
63: }
64: return(0);
65: }
69: /*@C
70: VecSetFromOptions - Configures the vector from the options database.
72: Collective on Vec
74: Input Parameter:
75: . vec - The vector
77: Notes: To see all options, run your program with the -help option, or consult the users manual.
78: Must be called after VecCreate() but before the vector is used.
80: Level: beginner
82: Concepts: vectors^setting options
83: Concepts: vectors^setting type
85: .keywords: Vec, set, options, database
86: .seealso: VecCreate(), VecPrintHelp(), VecSetOptionsPrefix()
87: @*/
88: PetscErrorCode VecSetFromOptions(Vec vec)
89: {
90: PetscTruth opt;
96: PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");
98: /* Handle generic vector options */
99: PetscOptionsHasName(PETSC_NULL, "-help", &opt);
100: if (opt) {
101: VecPrintHelp(vec);
102: }
104: /* Handle vector type options */
105: VecSetTypeFromOptions_Private(vec);
107: /* Handle specific vector options */
108: if (vec->ops->setfromoptions) {
109: (*vec->ops->setfromoptions)(vec);
110: }
111: PetscOptionsEnd();
113: VecViewFromOptions(vec, vec->name);
114: return(0);
115: }
119: /*@
120: VecPrintHelp - Prints some options for the Vec.
122: Input Parameter:
123: . vec - The vector
125: Options Database Keys:
126: $ -help, -h
128: Level: intermediate
130: .keywords: Vec, help
131: .seealso: VecSetFromOptions()
132: @*/
133: PetscErrorCode VecPrintHelp(Vec vec)
134: {
137: return(0);
138: }
142: /*@
143: VecSetSizes - Sets the local and global sizes, and checks to determine compatibility
145: Collective on Vec
147: Input Parameters:
148: + v - the vector
149: . n - the local size (or PETSC_DECIDE to have it set)
150: - N - the global size (or PETSC_DECIDE)
152: Notes:
153: n and N cannot be both PETSC_DECIDE
154: If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.
156: Level: intermediate
158: .seealso: VecGetSize(), PetscSplitOwnership()
159: @*/
160: PetscErrorCode VecSetSizes(Vec v, PetscInt n, PetscInt N)
161: {
164: if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
165: if ((v->n >= 0 || v->N >= 0) && (v->n != n || v->N != N)) SETERRQ4(PETSC_ERR_SUP,"Cannot change/reset vector sizes to %D local %D global after previously setting them to %D local %D global",n,N,v->n,v->N);
166: v->n = n;
167: v->N = N;
168: return(0);
169: }
173: /*@
174: VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
175: and VecSetValuesBlockedLocal().
177: Collective on Vec
179: Input Parameter:
180: + v - the vector
181: - bs - the blocksize
183: Notes:
184: All vectors obtained by VecDuplicate() inherit the same blocksize.
186: Level: advanced
188: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecGetBlockSize()
190: Concepts: block size^vectors
191: @*/
192: PetscErrorCode VecSetBlockSize(Vec v,PetscInt bs)
193: {
196: if (bs <= 0) bs = 1;
197: if (bs == v->bs) return(0);
198: if (v->bs != -1) SETERRQ2(PETSC_ERR_ARG_WRONGSTATE,"Cannot reset blocksize. Current size %D new %D",v->bs,bs);
199: if (v->N != -1 && v->N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %D %D",v->N,bs);
200: if (v->n != -1 && v->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
201: Try setting blocksize before setting the vector type",v->n,bs);
202:
203: v->bs = bs;
204: v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
205: return(0);
206: }
210: /*@
211: VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
212: and VecSetValuesBlockedLocal().
214: Collective on Vec
216: Input Parameter:
217: . v - the vector
219: Output Parameter:
220: . bs - the blocksize
222: Notes:
223: All vectors obtained by VecDuplicate() inherit the same blocksize.
225: Level: advanced
227: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecSetBlockSize()
229: Concepts: vector^block size
230: Concepts: block^vector
232: @*/
233: PetscErrorCode VecGetBlockSize(Vec v,PetscInt *bs)
234: {
238: *bs = v->bs;
239: return(0);
240: }
244: /*@
245: VecValid - Checks whether a vector object is valid.
247: Not Collective
249: Input Parameter:
250: . v - the object to check
252: Output Parameter:
253: flg - flag indicating vector status, either
254: PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.
256: Level: developer
258: @*/
259: PetscErrorCode VecValid(Vec v,PetscTruth *flg)
260: {
263: if (!v) *flg = PETSC_FALSE;
264: else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
265: else *flg = PETSC_TRUE;
266: return(0);
267: }
271: /*@
272: VecDot - Computes the vector dot product.
274: Collective on Vec
276: Input Parameters:
277: . x, y - the vectors
279: Output Parameter:
280: . alpha - the dot product
282: Performance Issues:
283: + per-processor memory bandwidth
284: . interprocessor latency
285: - work load inbalance that causes certain processes to arrive much earlier than
286: others
288: Notes for Users of Complex Numbers:
289: For complex vectors, VecDot() computes
290: $ val = (x,y) = y^H x,
291: where y^H denotes the conjugate transpose of y.
293: Use VecTDot() for the indefinite form
294: $ val = (x,y) = y^T x,
295: where y^T denotes the transpose of y.
297: Level: intermediate
299: Concepts: inner product
300: Concepts: vector^inner product
302: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
303: @*/
304: PetscErrorCode VecDot(Vec x,Vec y,PetscScalar *val)
305: {
315: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
316: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
318: PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
319: (*x->ops->dot)(x,y,val);
320: PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
321: /*
322: The next block is for incremental debugging
323: */
324: if (PetscCompare) {
325: PetscMPIInt flag;
326: MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
327: if (flag != MPI_UNEQUAL) {
328: PetscCompareScalar(*val);
329: }
330: }
331: return(0);
332: }
336: /*@
337: VecNorm - Computes the vector norm.
339: Collective on Vec
341: Input Parameters:
342: + x - the vector
343: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
344: NORM_1_AND_2, which computes both norms and stores them
345: in a two element array.
347: Output Parameter:
348: . val - the norm
350: Notes:
351: $ NORM_1 denotes sum_i |x_i|
352: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
353: $ NORM_INFINITY denotes max_i |x_i|
355: Level: intermediate
357: Performance Issues:
358: + per-processor memory bandwidth
359: . interprocessor latency
360: - work load inbalance that causes certain processes to arrive much earlier than
361: others
363: Compile Option:
364: PETSC_HAVE_SLOW_NRM2 will cause a C (loop unrolled) version of the norm to be used, rather
365: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
366: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
368: Concepts: norm
369: Concepts: vector^norm
371: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(),
372: VecNormBegin(), VecNormEnd()
374: @*/
375: PetscErrorCode VecNorm(Vec x,NormType type,PetscReal *val)
376: {
377: PetscTruth flg;
379: PetscInt type_id;
386: /*
387: * Cached data?
388: */
389: if (type!=NORM_1_AND_2) {
390: VecNormComposedDataID(type,&type_id);
391: PetscObjectGetRealComposedData((PetscObject)x,type_id,*val,flg);
392: if (flg) return(0);
393: }
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: PetscMPIInt 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: PetscErrorCode VecNormComposedDataID(NormType type,PetscInt *type_id)
421: {
422: static PetscInt id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
423: PetscErrorCode ierr;
426: switch (type) {
427: case NORM_1 :
428: if (id_norm1==-1) {
429: PetscRegisterComposedData(&id_norm1);}
430: *type_id = id_norm1; break;
431: case NORM_2 :
432: if (id_norm2==-1) {
433: PetscRegisterComposedData(&id_norm2);}
434: *type_id = id_norm2; break;
435: case NORM_1_AND_2 :
436: /* we don't handle this one yet */
437: if (id_norm1==-1) {
438: PetscRegisterComposedData(&id_norm1);}
439: if (id_norm2==-1) {
440: PetscRegisterComposedData(&id_norm2);}
441: *type_id = id_norm12; break;
442: case NORM_INFINITY :
443: if (id_normInf==-1) {
444: PetscRegisterComposedData(&id_normInf);}
445: *type_id = id_normInf; break;
446: case NORM_FROBENIUS :
447: if (id_normF==-1) {
448: PetscRegisterComposedData(&id_normF);}
449: *type_id = id_normF; break;
450: }
451: return(0);
452: }
456: /*@
457: VecNormalize - Normalizes a vector by 2-norm.
459: Collective on Vec
461: Input Parameters:
462: + x - the vector
464: Output Parameter:
465: . x - the normalized vector
466: - val - the vector norm before normalization
468: Level: intermediate
470: Concepts: vector^normalizing
471: Concepts: normalizing^vector
473: @*/
474: PetscErrorCode VecNormalize (Vec x,PetscReal *val)
475: {
482: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
483: VecNorm(x,NORM_2,val);
484: if (!*val) {
485: PetscLogInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm");
486: } else {
487: PetscScalar tmp = 1.0/(*val);
488: VecScale(&tmp,x);
489: }
491: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
492: return(0);
493: }
497: /*@C
498: VecMax - Determines the maximum vector component and its location.
500: Collective on Vec
502: Input Parameter:
503: . x - the vector
505: Output Parameters:
506: + val - the maximum component
507: - p - the location of val
509: Notes:
510: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
512: Level: intermediate
514: Concepts: maximum^of vector
515: Concepts: vector^maximum value
517: .seealso: VecNorm(), VecMin()
518: @*/
519: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
520: {
527: PetscLogEventBegin(VEC_Max,x,0,0,0);
528: (*x->ops->max)(x,p,val);
529: PetscLogEventEnd(VEC_Max,x,0,0,0);
530: return(0);
531: }
535: /*@
536: VecMin - Determines the minimum vector component and its location.
538: Collective on Vec
540: Input Parameters:
541: . x - the vector
543: Output Parameter:
544: + val - the minimum component
545: - p - the location of val
547: Level: intermediate
549: Notes:
550: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
552: Concepts: minimum^of vector
553: Concepts: vector^minimum entry
555: .seealso: VecMax()
556: @*/
557: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
558: {
565: PetscLogEventBegin(VEC_Min,x,0,0,0);
566: (*x->ops->min)(x,p,val);
567: PetscLogEventEnd(VEC_Min,x,0,0,0);
568: return(0);
569: }
573: /*@
574: VecTDot - Computes an indefinite vector dot product. That is, this
575: routine does NOT use the complex conjugate.
577: Collective on Vec
579: Input Parameters:
580: . x, y - the vectors
582: Output Parameter:
583: . val - the dot product
585: Notes for Users of Complex Numbers:
586: For complex vectors, VecTDot() computes the indefinite form
587: $ val = (x,y) = y^T x,
588: where y^T denotes the transpose of y.
590: Use VecDot() for the inner product
591: $ val = (x,y) = y^H x,
592: where y^H denotes the conjugate transpose of y.
594: Level: intermediate
596: Concepts: inner product^non-Hermitian
597: Concepts: vector^inner product
598: Concepts: non-Hermitian inner product
600: .seealso: VecDot(), VecMTDot()
601: @*/
602: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
603: {
613: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
614: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
616: PetscLogEventBegin(VEC_TDot,x,y,0,0);
617: (*x->ops->tdot)(x,y,val);
618: PetscLogEventEnd(VEC_TDot,x,y,0,0);
619: return(0);
620: }
624: /*@
625: VecScale - Scales a vector.
627: Collective on Vec
629: Input Parameters:
630: + x - the vector
631: - alpha - the scalar
633: Output Parameter:
634: . x - the scaled vector
636: Note:
637: For a vector with n components, VecScale() computes
638: $ x[i] = alpha * x[i], for i=1,...,n.
640: Level: intermediate
642: Concepts: vector^scaling
643: Concepts: scaling^vector
645: @*/
646: PetscErrorCode VecScale (const PetscScalar *alpha,Vec x)
647: {
648: PetscReal scale,norm1=0.0,norm2=0.0,normInf=0.0,normF=0.0;
649: PetscTruth flg1,flg2,flgInf,flgF;
651: PetscInt type_id1,type_id2,type_idInf,type_idF;
657: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
658: PetscLogEventBegin(VEC_Scale,x,0,0,0);
659: (*x->ops->scale)(alpha,x);
661: /*
662: * Update cached data
663: */
664: /* see if we have cached norms */
665: /* 1 */
666: VecNormComposedDataID(NORM_1,&type_id1);
667: PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1,flg1);
668: /* 2 */
669: VecNormComposedDataID(NORM_2,&type_id2);
670: PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2,flg2);
671: /* inf */
672: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
673: PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInf,flgInf);
674: /* frobenius */
675: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
676: PetscObjectGetRealComposedData((PetscObject)x,type_idF,normF,flgF);
678: /* in general we consider this object touched */
679: PetscObjectIncreaseState((PetscObject)x);
681: /* however, norms can be simply updated */
682: scale = PetscAbsScalar(*alpha);
683: /* 1 */
684: if (flg1) {
685: PetscObjectSetRealComposedData((PetscObject)x,type_id1,scale*norm1);
686: }
687: /* 2 */
688: if (flg2) {
689: PetscObjectSetRealComposedData((PetscObject)x,type_id2,scale*norm2);
690: }
691: /* inf */
692: if (flgInf) {
693: PetscObjectSetRealComposedData((PetscObject)x,type_idInf,scale*normInf);
694: }
695: /* frobenius */
696: if (flgF) {
697: PetscObjectSetRealComposedData((PetscObject)x,type_idF,scale*normF);
698: }
700: PetscLogEventEnd(VEC_Scale,x,0,0,0);
701: return(0);
702: }
706: /*@
707: VecCopy - Copies a vector.
709: Collective on Vec
711: Input Parameter:
712: . x - the vector
714: Output Parameter:
715: . y - the copy
717: Notes:
718: For default parallel PETSc vectors, both x and y must be distributed in
719: the same manner; local copies are done.
721: Level: beginner
723: .seealso: VecDuplicate()
724: @*/
725: PetscErrorCode VecCopy(Vec x,Vec y)
726: {
727: PetscTruth flg;
728: PetscReal norm=0.0;
730: PetscInt type_id;
738: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
739: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
741: PetscLogEventBegin(VEC_Copy,x,y,0,0);
742: (*x->ops->copy)(x,y);
744: /*
745: * Update cached data
746: */
747: /* in general we consider this object touched */
748: PetscObjectIncreaseState((PetscObject)y);
749: /* however, norms can be simply copied over */
750: /* 2 */
751: VecNormComposedDataID(NORM_2,&type_id);
752: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
753: if (flg) {
754: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
755: }
756: /* 1 */
757: VecNormComposedDataID(NORM_1,&type_id);
758: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
759: if (flg) {
760: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
761: }
762: /* inf */
763: VecNormComposedDataID(NORM_INFINITY,&type_id);
764: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
765: if (flg) {
766: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
767: }
768: /* frobenius */
769: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
770: PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
771: if (flg) {
772: PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
773: }
775: PetscLogEventEnd(VEC_Copy,x,y,0,0);
776: return(0);
777: }
781: /*@
782: VecSet - Sets all components of a vector to a single scalar value.
784: Collective on Vec
786: Input Parameters:
787: + alpha - the scalar
788: - x - the vector
790: Output Parameter:
791: . x - the vector
793: Note:
794: For a vector of dimension n, VecSet() computes
795: $ x[i] = alpha, for i=1,...,n,
796: so that all vector entries then equal the identical
797: scalar value, alpha. Use the more general routine
798: VecSetValues() to set different vector entries.
800: You CANNOT call this after you have called VecSetValues() but before you call
801: VecAssemblyBegin/End().
803: Level: beginner
805: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
807: Concepts: vector^setting to constant
809: @*/
810: PetscErrorCode VecSet(const PetscScalar *alpha,Vec x)
811: {
812: PetscReal val;
814: PetscInt type_id;
820: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"You cannot call this after you have called VecSetValues() but\n before you have called VecAssemblyBegin/End()");
822: PetscLogEventBegin(VEC_Set,x,0,0,0);
823: (*x->ops->set)(alpha,x);
824: PetscLogEventEnd(VEC_Set,x,0,0,0);
826: /*
827: * Update cached data
828: */
829: /* in general we consider this object touched */
830: PetscObjectIncreaseState((PetscObject)x);
831: /* however, norms can be simply set */
832: /* 1 */
833: val = PetscAbsScalar(*alpha);
834: VecNormComposedDataID(NORM_1,&type_id);
835: PetscObjectSetRealComposedData((PetscObject)x,type_id,x->N * val);
836: /* inf */
837: VecNormComposedDataID(NORM_INFINITY,&type_id);
838: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
839: /* 2 */
840: val = sqrt((double)x->N) * val;
841: VecNormComposedDataID(NORM_2,&type_id);
842: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
843: /* frobenius */
844: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
845: PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
847: return(0);
848: }
852: /*@C
853: VecSetRandom - Sets all components of a vector to random numbers.
855: Collective on Vec
857: Input Parameters:
858: + rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
859: it will create one internally.
860: - x - the vector
862: Output Parameter:
863: . x - the vector
865: Example of Usage:
866: .vb
867: PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
868: VecSetRandom(rctx,x);
869: PetscRandomDestroy(rctx);
870: .ve
872: Level: intermediate
874: Concepts: vector^setting to random
875: Concepts: random^vector
877: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
878: @*/
879: PetscErrorCode VecSetRandom(PetscRandom rctx,Vec x)
880: {
882: PetscRandom randObj = PETSC_NULL;
888: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
890: if (!rctx) {
891: MPI_Comm comm;
892: PetscObjectGetComm((PetscObject)x,&comm);
893: PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
894: rctx = randObj;
895: }
897: PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
898: (*x->ops->setrandom)(rctx,x);
899: PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
900:
901: if (randObj) {
902: PetscRandomDestroy(randObj);
903: }
904: PetscObjectIncreaseState((PetscObject)x);
905: return(0);
906: }
910: /*@
911: VecAXPY - Computes y = alpha x + y.
913: Collective on Vec
915: Input Parameters:
916: + alpha - the scalar
917: - x, y - the vectors
919: Output Parameter:
920: . y - output vector
922: Level: intermediate
924: Concepts: vector^BLAS
925: Concepts: BLAS
927: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
928: @*/
929: PetscErrorCode VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
930: {
940: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
941: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
943: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
944: (*x->ops->axpy)(alpha,x,y);
945: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
946: PetscObjectIncreaseState((PetscObject)y);
947: return(0);
948: }
952: /*@
953: VecAXPBY - Computes y = alpha x + beta y.
955: Collective on Vec
957: Input Parameters:
958: + alpha,beta - the scalars
959: - x, y - the vectors
961: Output Parameter:
962: . y - output vector
964: Level: intermediate
966: Concepts: BLAS
967: Concepts: vector^BLAS
969: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
970: @*/
971: PetscErrorCode VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
972: {
983: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
984: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
986: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
987: (*x->ops->axpby)(alpha,beta,x,y);
988: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
989: PetscObjectIncreaseState((PetscObject)y);
990: return(0);
991: }
995: /*@
996: VecAYPX - Computes y = x + alpha y.
998: Collective on Vec
1000: Input Parameters:
1001: + alpha - the scalar
1002: - x, y - the vectors
1004: Output Parameter:
1005: . y - output vector
1007: Level: intermediate
1009: Concepts: vector^BLAS
1010: Concepts: BLAS
1012: .seealso: VecAXPY(), VecWAXPY()
1013: @*/
1014: PetscErrorCode VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
1015: {
1025: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1026: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1028: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1029: (*x->ops->aypx)(alpha,x,y);
1030: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1031: PetscObjectIncreaseState((PetscObject)y);
1032: return(0);
1033: }
1037: /*@
1038: VecSwap - Swaps the vectors x and y.
1040: Collective on Vec
1042: Input Parameters:
1043: . x, y - the vectors
1045: Level: advanced
1047: Concepts: vector^swapping values
1049: @*/
1050: PetscErrorCode VecSwap(Vec x,Vec y)
1051: {
1052: PetscReal norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1053: PetscReal norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1054: PetscTruth flg1x,flg2x,flgInfx,flgFx;
1055: PetscTruth flg1y,flg2y,flgInfy,flgFy;
1056: PetscInt type_id1,type_id2,type_idInf,type_idF;
1065: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1066: if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1067: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1068: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1070: PetscLogEventBegin(VEC_Swap,x,y,0,0);
1072: /* See if we have cached norms */
1073: /* 1 */
1074: VecNormComposedDataID(NORM_1,&type_id1);
1075: PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1x,flg1x);
1076: PetscObjectGetRealComposedData((PetscObject)y,type_id1,norm1y,flg1y);
1077: /* 2 */
1078: VecNormComposedDataID(NORM_2,&type_id2);
1079: PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2x,flg2x);
1080: PetscObjectGetRealComposedData((PetscObject)y,type_id2,norm2y,flg2y);
1081: /* inf */
1082: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1083: PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInfx,flgInfx);
1084: PetscObjectGetRealComposedData((PetscObject)y,type_idInf,normInfy,flgInfy);
1085: /* frobenius */
1086: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1087: PetscObjectGetRealComposedData((PetscObject)x,type_idF,normFx,flgFx);
1088: PetscObjectGetRealComposedData((PetscObject)y,type_idF,normFy,flgFy);
1090: /* Do the actual swap */
1091: (*x->ops->swap)(x,y);
1092: PetscObjectIncreaseState((PetscObject)x);
1093: PetscObjectIncreaseState((PetscObject)y);
1095: /* Swap any cached norms */
1096: /* 1 */
1097: if (flg1x) {
1098: PetscObjectSetRealComposedData((PetscObject)y,type_id1,norm1x);
1099: }
1100: if (flg1y) {
1101: PetscObjectSetRealComposedData((PetscObject)x,type_id1,norm1y);
1102: }
1103: /* 2 */
1104: if (flg2x) {
1105: PetscObjectSetRealComposedData((PetscObject)y,type_id2,norm2x);
1106: }
1107: if (flg2y) {
1108: PetscObjectSetRealComposedData((PetscObject)x,type_id2,norm2y);
1109: }
1110: /* inf */
1111: if (flgInfx) {
1112: PetscObjectSetRealComposedData((PetscObject)y,type_idInf,normInfx);
1113: }
1114: if (flgInfy) {
1115: PetscObjectSetRealComposedData((PetscObject)x,type_idInf,normInfy);
1116: }
1117: /* frobenius */
1118: if (flgFx) {
1119: PetscObjectSetRealComposedData((PetscObject)y,type_idF,normFx);
1120: }
1121: if (flgFy) {
1122: PetscObjectSetRealComposedData((PetscObject)x,type_idF,normFy);
1123: }
1125: PetscLogEventEnd(VEC_Swap,x,y,0,0);
1127: return(0);
1128: }
1132: /*@
1133: VecWAXPY - Computes w = alpha x + y.
1135: Collective on Vec
1137: Input Parameters:
1138: + alpha - the scalar
1139: - x, y - the vectors
1141: Output Parameter:
1142: . w - the result
1144: Level: intermediate
1146: Concepts: vector^BLAS
1147: Concepts: BLAS
1149: .seealso: VecAXPY(), VecAYPX()
1150: @*/
1151: PetscErrorCode VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
1152: {
1165: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1166: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1168: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1169: (*x->ops->waxpy)(alpha,x,y,w);
1170: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1171: PetscObjectIncreaseState((PetscObject)w);
1172: return(0);
1173: }
1177: /*@
1178: VecPointwiseMult - Computes the componentwise multiplication w = x*y.
1180: Collective on Vec
1182: Input Parameters:
1183: . x, y - the vectors
1185: Output Parameter:
1186: . w - the result
1188: Level: advanced
1190: Notes: any subset of the x, y, and w may be the same vector.
1192: Concepts: vector^pointwise multiply
1194: .seealso: VecPointwiseDivide()
1195: @*/
1196: PetscErrorCode VecPointwiseMult(Vec x,Vec y,Vec w)
1197: {
1209: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1210: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1212: PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1213: (*x->ops->pointwisemult)(x,y,w);
1214: PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1215: PetscObjectIncreaseState((PetscObject)w);
1216: return(0);
1217: }
1221: /*@
1222: VecPointwiseDivide - Computes the componentwise division w = x/y.
1224: Collective on Vec
1226: Input Parameters:
1227: . x, y - the vectors
1229: Output Parameter:
1230: . w - the result
1232: Level: advanced
1234: Notes: any subset of the x, y, and w may be the same vector.
1236: Concepts: vector^pointwise divide
1238: .seealso: VecPointwiseMult()
1239: @*/
1240: PetscErrorCode VecPointwiseDivide(Vec x,Vec y,Vec w)
1241: {
1253: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1254: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1256: (*x->ops->pointwisedivide)(x,y,w);
1257: PetscObjectIncreaseState((PetscObject)w);
1258: return(0);
1259: }
1263: /*@
1264: VecMaxPointwiseDivide - Computes the maximum of the componentwise division w = abs(x/y).
1266: Collective on Vec
1268: Input Parameters:
1269: . x, y - the vectors
1271: Output Parameter:
1272: . max - the result
1274: Level: advanced
1276: Notes: any subset of the x, y, and w may be the same vector.
1278: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1279: @*/
1280: PetscErrorCode VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1281: {
1291: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1292: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1294: (*x->ops->maxpointwisedivide)(x,y,max);
1295: return(0);
1296: }
1300: /*@C
1301: VecDuplicate - Creates a new vector of the same type as an existing vector.
1303: Collective on Vec
1305: Input Parameters:
1306: . v - a vector to mimic
1308: Output Parameter:
1309: . newv - location to put new vector
1311: Notes:
1312: VecDuplicate() does not copy the vector, but rather allocates storage
1313: for the new vector. Use VecCopy() to copy a vector.
1315: Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1316: vectors.
1318: Level: beginner
1320: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1321: @*/
1322: PetscErrorCode VecDuplicate(Vec x,Vec *newv)
1323: {
1330: (*x->ops->duplicate)(x,newv);
1331: PetscObjectIncreaseState((PetscObject)*newv);
1332: return(0);
1333: }
1337: /*@C
1338: VecDestroy - Destroys a vector.
1340: Collective on Vec
1342: Input Parameters:
1343: . v - the vector
1345: Level: beginner
1347: .seealso: VecDuplicate(), VecDestroyVecs()
1348: @*/
1349: PetscErrorCode VecDestroy(Vec v)
1350: {
1355: if (--v->refct > 0) return(0);
1356: /* destroy the internal part */
1357: if (v->ops->destroy) {
1358: (*v->ops->destroy)(v);
1359: }
1360: /* destroy the external/common part */
1361: if (v->mapping) {
1362: ISLocalToGlobalMappingDestroy(v->mapping);
1363: }
1364: if (v->bmapping) {
1365: ISLocalToGlobalMappingDestroy(v->bmapping);
1366: }
1367: if (v->map) {
1368: PetscMapDestroy(v->map);
1369: }
1370: PetscLogObjectDestroy(v);
1371: PetscHeaderDestroy(v);
1372: return(0);
1373: }
1377: /*@C
1378: VecDuplicateVecs - Creates several vectors of the same type as an existing vector.
1380: Collective on Vec
1382: Input Parameters:
1383: + m - the number of vectors to obtain
1384: - v - a vector to mimic
1386: Output Parameter:
1387: . V - location to put pointer to array of vectors
1389: Notes:
1390: Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1391: vector.
1393: Fortran Note:
1394: The Fortran interface is slightly different from that given below, it
1395: requires one to pass in V a Vec (integer) array of size at least m.
1396: See the Fortran chapter of the users manual and petsc/src/vec/examples for details.
1398: Level: intermediate
1400: .seealso: VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1401: @*/
1402: PetscErrorCode VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
1403: {
1410: (*v->ops->duplicatevecs)(v, m,V);
1411: return(0);
1412: }
1416: /*@C
1417: VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().
1419: Collective on Vec
1421: Input Parameters:
1422: + vv - pointer to array of vector pointers
1423: - m - the number of vectors previously obtained
1425: Fortran Note:
1426: The Fortran interface is slightly different from that given below.
1427: See the Fortran chapter of the users manual and
1428: petsc/src/vec/examples for details.
1430: Level: intermediate
1432: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
1433: @*/
1434: PetscErrorCode VecDestroyVecs(Vec vv[],PetscInt m)
1435: {
1442: (*(*vv)->ops->destroyvecs)(vv,m);
1443: return(0);
1444: }
1449: /*@
1450: VecSetValues - Inserts or adds values into certain locations of a vector.
1452: Input Parameters:
1453: Not Collective
1455: + x - vector to insert in
1456: . ni - number of elements to add
1457: . ix - indices where to add
1458: . y - array of values
1459: - iora - either INSERT_VALUES or ADD_VALUES, where
1460: ADD_VALUES adds values to any existing entries, and
1461: INSERT_VALUES replaces existing entries with new values
1463: Notes:
1464: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1466: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1467: options cannot be mixed without intervening calls to the assembly
1468: routines.
1470: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1471: MUST be called after all calls to VecSetValues() have been completed.
1473: VecSetValues() uses 0-based indices in Fortran as well as in C.
1475: Negative indices may be passed in ix, these rows are
1476: simply ignored. This allows easily inserting element load matrices
1477: with homogeneous Dirchlet boundary conditions that you don't want represented
1478: in the vector.
1480: Level: beginner
1482: Concepts: vector^setting values
1484: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1485: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES
1486: @*/
1487: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1488: {
1496: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1497: (*x->ops->setvalues)(x,ni,ix,y,iora);
1498: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1499: PetscObjectIncreaseState((PetscObject)x);
1500: return(0);
1501: }
1505: /*@
1506: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
1508: Not Collective
1510: Input Parameters:
1511: + x - vector to insert in
1512: . ni - number of blocks to add
1513: . ix - indices where to add in block count, rather than element count
1514: . y - array of values
1515: - iora - either INSERT_VALUES or ADD_VALUES, where
1516: ADD_VALUES adds values to any existing entries, and
1517: INSERT_VALUES replaces existing entries with new values
1519: Notes:
1520: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
1521: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
1523: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1524: options cannot be mixed without intervening calls to the assembly
1525: routines.
1527: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1528: MUST be called after all calls to VecSetValuesBlocked() have been completed.
1530: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
1532: Negative indices may be passed in ix, these rows are
1533: simply ignored. This allows easily inserting element load matrices
1534: with homogeneous Dirchlet boundary conditions that you don't want represented
1535: in the vector.
1537: Level: intermediate
1539: Concepts: vector^setting values blocked
1541: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1542: VecSetValues()
1543: @*/
1544: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1545: {
1553: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1554: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1555: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1556: PetscObjectIncreaseState((PetscObject)x);
1557: return(0);
1558: }
1562: /*@
1563: VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1564: by the routine VecSetValuesLocal() to allow users to insert vector entries
1565: using a local (per-processor) numbering.
1567: Collective on Vec
1569: Input Parameters:
1570: + x - vector
1571: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1573: Notes:
1574: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1576: Level: intermediate
1578: Concepts: vector^setting values with local numbering
1580: seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1581: VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1582: @*/
1583: PetscErrorCode VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1584: {
1591: if (x->mapping) {
1592: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1593: }
1595: if (x->ops->setlocaltoglobalmapping) {
1596: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1597: } else {
1598: x->mapping = mapping;
1599: PetscObjectReference((PetscObject)mapping);
1600: }
1601: return(0);
1602: }
1606: /*@
1607: VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1608: by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1609: using a local (per-processor) numbering.
1611: Collective on Vec
1613: Input Parameters:
1614: + x - vector
1615: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1617: Notes:
1618: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1620: Level: intermediate
1622: Concepts: vector^setting values blocked with local numbering
1624: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1625: VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1626: @*/
1627: PetscErrorCode VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1628: {
1635: if (x->bmapping) {
1636: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1637: }
1638: x->bmapping = mapping;
1639: PetscObjectReference((PetscObject)mapping);
1640: return(0);
1641: }
1645: /*@
1646: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1647: using a local ordering of the nodes.
1649: Not Collective
1651: Input Parameters:
1652: + x - vector to insert in
1653: . ni - number of elements to add
1654: . ix - indices where to add
1655: . y - array of values
1656: - iora - either INSERT_VALUES or ADD_VALUES, where
1657: ADD_VALUES adds values to any existing entries, and
1658: INSERT_VALUES replaces existing entries with new values
1660: Level: intermediate
1662: Notes:
1663: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1665: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1666: options cannot be mixed without intervening calls to the assembly
1667: routines.
1669: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1670: MUST be called after all calls to VecSetValuesLocal() have been completed.
1672: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
1674: Concepts: vector^setting values with local numbering
1676: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1677: VecSetValuesBlockedLocal()
1678: @*/
1679: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1680: {
1682: PetscInt lixp[128],*lix = lixp;
1690: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1691: if (!x->ops->setvalueslocal) {
1692: if (!x->mapping) {
1693: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1694: }
1695: if (ni > 128) {
1696: PetscMalloc(ni*sizeof(PetscInt),&lix);
1697: }
1698: ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
1699: (*x->ops->setvalues)(x,ni,lix,y,iora);
1700: if (ni > 128) {
1701: PetscFree(lix);
1702: }
1703: } else {
1704: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1705: }
1706: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1707: PetscObjectIncreaseState((PetscObject)x);
1708: return(0);
1709: }
1713: /*@
1714: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1715: using a local ordering of the nodes.
1717: Not Collective
1719: Input Parameters:
1720: + x - vector to insert in
1721: . ni - number of blocks to add
1722: . ix - indices where to add in block count, not element count
1723: . y - array of values
1724: - iora - either INSERT_VALUES or ADD_VALUES, where
1725: ADD_VALUES adds values to any existing entries, and
1726: INSERT_VALUES replaces existing entries with new values
1728: Level: intermediate
1730: Notes:
1731: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
1732: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
1734: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1735: options cannot be mixed without intervening calls to the assembly
1736: routines.
1738: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1739: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
1741: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
1744: Concepts: vector^setting values blocked with local numbering
1746: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
1747: VecSetLocalToGlobalMappingBlocked()
1748: @*/
1749: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1750: {
1752: PetscInt lixp[128],*lix = lixp;
1759: if (!x->bmapping) {
1760: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1761: }
1762: if (ni > 128) {
1763: PetscMalloc(ni*sizeof(PetscInt),&lix);
1764: }
1766: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1767: ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
1768: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1769: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1770: if (ni > 128) {
1771: PetscFree(lix);
1772: }
1773: PetscObjectIncreaseState((PetscObject)x);
1774: return(0);
1775: }
1779: /*@
1780: VecAssemblyBegin - Begins assembling the vector. This routine should
1781: be called after completing all calls to VecSetValues().
1783: Collective on Vec
1785: Input Parameter:
1786: . vec - the vector
1788: Level: beginner
1790: Concepts: assembly^vectors
1792: .seealso: VecAssemblyEnd(), VecSetValues()
1793: @*/
1794: PetscErrorCode VecAssemblyBegin(Vec vec)
1795: {
1797: PetscTruth flg;
1803: PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1804: if (flg) {
1805: VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1806: }
1808: PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1809: if (vec->ops->assemblybegin) {
1810: (*vec->ops->assemblybegin)(vec);
1811: }
1812: PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1813: PetscObjectIncreaseState((PetscObject)vec);
1814: return(0);
1815: }
1819: /*@
1820: VecAssemblyEnd - Completes assembling the vector. This routine should
1821: be called after VecAssemblyBegin().
1823: Collective on Vec
1825: Input Parameter:
1826: . vec - the vector
1828: Options Database Keys:
1829: + -vec_view - Prints vector in ASCII format
1830: . -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
1831: . -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
1832: . -vec_view_draw - Activates vector viewing using drawing tools
1833: . -display <name> - Sets display name (default is host)
1834: . -draw_pause <sec> - Sets number of seconds to pause after display
1835: - -vec_view_socket - Activates vector viewing using a socket
1836:
1837: Level: beginner
1839: .seealso: VecAssemblyBegin(), VecSetValues()
1840: @*/
1841: PetscErrorCode VecAssemblyEnd(Vec vec)
1842: {
1844: PetscTruth flg;
1848: PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
1850: if (vec->ops->assemblyend) {
1851: (*vec->ops->assemblyend)(vec);
1852: }
1853: PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
1854: PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
1855: PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
1856: if (flg) {
1857: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1858: }
1859: PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
1860: if (flg) {
1861: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
1862: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1863: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
1864: }
1865: #if defined(PETSC_HAVE_MATLAB) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
1866: PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
1867: if (flg) {
1868: VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
1869: }
1870: #endif
1871: PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
1872: if (flg) {
1873: VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
1874: PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
1875: }
1876: PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
1877: if (flg) {
1878: VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
1879: PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
1880: }
1881: PetscOptionsEnd();
1882: /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
1883: /* hence they should not be inside the above PetscOptionsBegin/End block. */
1884: PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
1885: if (flg) {
1886: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1887: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1888: }
1889: PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
1890: if (flg) {
1891: PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
1892: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1893: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1894: }
1895: return(0);
1896: }
1901: /*@C
1902: VecMTDot - Computes indefinite vector multiple dot products.
1903: That is, it does NOT use the complex conjugate.
1905: Collective on Vec
1907: Input Parameters:
1908: + nv - number of vectors
1909: . x - one vector
1910: - y - array of vectors. Note that vectors are pointers
1912: Output Parameter:
1913: . val - array of the dot products
1915: Notes for Users of Complex Numbers:
1916: For complex vectors, VecMTDot() computes the indefinite form
1917: $ val = (x,y) = y^T x,
1918: where y^T denotes the transpose of y.
1920: Use VecMDot() for the inner product
1921: $ val = (x,y) = y^H x,
1922: where y^H denotes the conjugate transpose of y.
1924: Level: intermediate
1926: Concepts: inner product^multiple
1927: Concepts: vector^multiple inner products
1929: .seealso: VecMDot(), VecTDot()
1930: @*/
1931: PetscErrorCode VecMTDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
1932: {
1943: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1944: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1946: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1947: (*x->ops->mtdot)(nv,x,y,val);
1948: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1949: return(0);
1950: }
1954: /*@C
1955: VecMDot - Computes vector multiple dot products.
1957: Collective on Vec
1959: Input Parameters:
1960: + nv - number of vectors
1961: . x - one vector
1962: - y - array of vectors.
1964: Output Parameter:
1965: . val - array of the dot products
1967: Notes for Users of Complex Numbers:
1968: For complex vectors, VecMDot() computes
1969: $ val = (x,y) = y^H x,
1970: where y^H denotes the conjugate transpose of y.
1972: Use VecMTDot() for the indefinite form
1973: $ val = (x,y) = y^T x,
1974: where y^T denotes the transpose of y.
1976: Level: intermediate
1978: Concepts: inner product^multiple
1979: Concepts: vector^multiple inner products
1981: .seealso: VecMTDot(), VecDot()
1982: @*/
1983: PetscErrorCode VecMDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
1984: {
1995: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1996: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1998: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1999: (*x->ops->mdot)(nv,x,y,val);
2000: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
2001: return(0);
2002: }
2006: /*@C
2007: VecMAXPY - Computes y = y + sum alpha[j] x[j]
2009: Collective on Vec
2011: Input Parameters:
2012: + nv - number of scalars and x-vectors
2013: . alpha - array of scalars
2014: . y - one vector
2015: - x - array of vectors
2017: Level: intermediate
2019: Concepts: BLAS
2021: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2022: @*/
2023: PetscErrorCode VecMAXPY(PetscInt nv,const PetscScalar *alpha,Vec y,Vec *x)
2024: {
2035: if (y->N != (*x)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2036: if (y->n != (*x)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
2038: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2039: (*y->ops->maxpy)(nv,alpha,y,x);
2040: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2041: PetscObjectIncreaseState((PetscObject)y);
2042: return(0);
2043: }
2045: /*MC
2046: VecGetArray - Returns a pointer to a contiguous array that contains this
2047: processor's portion of the vector data. For the standard PETSc
2048: vectors, VecGetArray() returns a pointer to the local data array and
2049: does not use any copies. If the underlying vector data is not stored
2050: in a contiquous array this routine will copy the data to a contiquous
2051: array and return a pointer to that. You MUST call VecRestoreArray()
2052: when you no longer need access to the array.
2054: Synopsis:
2055: PetscErrorCode VecGetArray(Vec x,PetscScalar *a)
2057: Not Collective
2059: Input Parameter:
2060: . x - the vector
2062: Output Parameter:
2063: . a - location to put pointer to the array
2065: Fortran Note:
2066: This routine is used differently from Fortran 77
2067: $ Vec x
2068: $ PetscScalar x_array(1)
2069: $ PetscOffset i_x
2070: $ PetscErrorCode ierr
2071: $ call VecGetArray(x,x_array,i_x,ierr)
2072: $
2073: $ Access first local entry in vector with
2074: $ value = x_array(i_x + 1)
2075: $
2076: $ ...... other code
2077: $ call VecRestoreArray(x,x_array,i_x,ierr)
2078: For Fortran 90 see VecGetArrayF90()
2080: See the Fortran chapter of the users manual and
2081: petsc/src/snes/examples/tutorials/ex5f.F for details.
2083: Level: beginner
2085: Concepts: vector^accessing local values
2087: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2088: M*/
2091: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
2092: {
2099: (*x->ops->getarray)(x,a);
2100: return(0);
2101: }
2106: /*@C
2107: VecGetArrays - Returns a pointer to the arrays in a set of vectors
2108: that were created by a call to VecDuplicateVecs(). You MUST call
2109: VecRestoreArrays() when you no longer need access to the array.
2111: Not Collective
2113: Input Parameter:
2114: + x - the vectors
2115: - n - the number of vectors
2117: Output Parameter:
2118: . a - location to put pointer to the array
2120: Fortran Note:
2121: This routine is not supported in Fortran.
2123: Level: intermediate
2125: .seealso: VecGetArray(), VecRestoreArrays()
2126: @*/
2127: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2128: {
2130: PetscInt i;
2131: PetscScalar **q;
2137: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
2138: PetscMalloc(n*sizeof(PetscScalar*),&q);
2139: for (i=0; i<n; ++i) {
2140: VecGetArray(x[i],&q[i]);
2141: }
2142: *a = q;
2143: return(0);
2144: }
2148: /*@C
2149: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2150: has been called.
2152: Not Collective
2154: Input Parameters:
2155: + x - the vector
2156: . n - the number of vectors
2157: - a - location of pointer to arrays obtained from VecGetArrays()
2159: Notes:
2160: For regular PETSc vectors this routine does not involve any copies. For
2161: any special vectors that do not store local vector data in a contiguous
2162: array, this routine will copy the data back into the underlying
2163: vector data structure from the arrays obtained with VecGetArrays().
2165: Fortran Note:
2166: This routine is not supported in Fortran.
2168: Level: intermediate
2170: .seealso: VecGetArrays(), VecRestoreArray()
2171: @*/
2172: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2173: {
2175: PetscInt i;
2176: PetscScalar **q = *a;
2183: for(i=0;i<n;++i) {
2184: VecRestoreArray(x[i],&q[i]);
2185: }
2186: PetscFree(q);
2187: return(0);
2188: }
2190: /*MC
2191: VecRestoreArray - Restores a vector after VecGetArray() has been called.
2193: Not Collective
2195: Synopsis:
2196: PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a)
2198: Input Parameters:
2199: + x - the vector
2200: - a - location of pointer to array obtained from VecGetArray()
2202: Level: beginner
2204: Notes:
2205: For regular PETSc vectors this routine does not involve any copies. For
2206: any special vectors that do not store local vector data in a contiguous
2207: array, this routine will copy the data back into the underlying
2208: vector data structure from the array obtained with VecGetArray().
2210: This routine actually zeros out the a pointer. This is to prevent accidental
2211: us of the array after it has been restored. If you pass null for a it will
2212: not zero the array pointer a.
2214: Fortran Note:
2215: This routine is used differently from Fortran 77
2216: $ Vec x
2217: $ PetscScalar x_array(1)
2218: $ PetscOffset i_x
2219: $ PetscErrorCode ierr
2220: $ call VecGetArray(x,x_array,i_x,ierr)
2221: $
2222: $ Access first local entry in vector with
2223: $ value = x_array(i_x + 1)
2224: $
2225: $ ...... other code
2226: $ call VecRestoreArray(x,x_array,i_x,ierr)
2228: See the Fortran chapter of the users manual and
2229: petsc/src/snes/examples/tutorials/ex5f.F for details.
2230: For Fortran 90 see VecRestoreArrayF90()
2232: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2233: M*/
2236: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
2237: {
2244: #if defined(PETSC_USE_BOPT_g)
2245: CHKMEMQ;
2246: #endif
2247: if (x->ops->restorearray) {
2248: (*x->ops->restorearray)(x,a);
2249: }
2250: PetscObjectIncreaseState((PetscObject)x);
2251: return(0);
2252: }
2254: #undef __FUNCT__
2256: /*@
2257: VecViewFromOptions - This function visualizes the vector based upon user options.
2259: Collective on Vec
2261: Input Parameters:
2262: . vec - The vector
2263: . title - The title
2265: Level: intermediate
2267: .keywords: Vec, view, options, database
2268: .seealso: VecSetFromOptions(), VecView()
2269: @*/
2270: PetscErrorCode VecViewFromOptions(Vec vec, char *title)
2271: {
2272: PetscViewer viewer;
2273: PetscDraw draw;
2274: PetscTruth opt;
2275: char *titleStr;
2276: char typeName[1024];
2277: char fileName[PETSC_MAX_PATH_LEN];
2278: size_t len;
2282: PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2283: if (opt == PETSC_TRUE) {
2284: PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2285: PetscStrlen(typeName, &len);
2286: if (len > 0) {
2287: PetscViewerCreate(vec->comm, &viewer);
2288: PetscViewerSetType(viewer, typeName);
2289: PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2290: if (opt == PETSC_TRUE) {
2291: PetscViewerSetFilename(viewer, fileName);
2292: } else {
2293: PetscViewerSetFilename(viewer, vec->name);
2294: }
2295: VecView(vec, viewer);
2296: PetscViewerFlush(viewer);
2297: PetscViewerDestroy(viewer);
2298: } else {
2299: VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2300: }
2301: }
2302: PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2303: if (opt == PETSC_TRUE) {
2304: PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2305: PetscViewerDrawGetDraw(viewer, 0, &draw);
2306: if (title != PETSC_NULL) {
2307: titleStr = title;
2308: } else {
2309: PetscObjectName((PetscObject) vec);
2310: titleStr = vec->name;
2311: }
2312: PetscDrawSetTitle(draw, titleStr);
2313: VecView(vec, viewer);
2314: PetscViewerFlush(viewer);
2315: PetscDrawPause(draw);
2316: PetscViewerDestroy(viewer);
2317: }
2318: return(0);
2319: }
2323: /*@C
2324: VecView - Views a vector object.
2326: Collective on Vec
2328: Input Parameters:
2329: + v - the vector
2330: - viewer - an optional visualization context
2332: Notes:
2333: The available visualization contexts include
2334: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
2335: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2336: output where only the first processor opens
2337: the file. All other processors send their
2338: data to the first processor to print.
2340: You can change the format the vector is printed using the
2341: option PetscViewerSetFormat().
2343: The user can open alternative visualization contexts with
2344: + PetscViewerASCIIOpen() - Outputs vector to a specified file
2345: . PetscViewerBinaryOpen() - Outputs vector in binary to a
2346: specified file; corresponding input uses VecLoad()
2347: . PetscViewerDrawOpen() - Outputs vector to an X window display
2348: - PetscViewerSocketOpen() - Outputs vector to Socket viewer
2350: The user can call PetscViewerSetFormat() to specify the output
2351: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2352: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
2353: + PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2354: . PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2355: . PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2356: - PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
2357: format common among all vector types
2359: Level: beginner
2361: Concepts: vector^printing
2362: Concepts: vector^saving to disk
2364: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2365: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2366: PetscRealView(), PetscScalarView(), PetscIntView()
2367: @*/
2368: PetscErrorCode VecView(Vec vec,PetscViewer viewer)
2369: {
2370: PetscErrorCode ierr;
2371: PetscViewerFormat format;
2376: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
2379: if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");
2381: /*
2382: Check if default viewer has been overridden, but user request it anyways
2383: */
2384: PetscViewerGetFormat(viewer,&format);
2385: if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2386: PetscViewerPopFormat(viewer);
2387: (*vec->ops->viewnative)(vec,viewer);
2388: PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2389: } else {
2390: (*vec->ops->view)(vec,viewer);
2391: }
2392: return(0);
2393: }
2397: /*@
2398: VecGetSize - Returns the global number of elements of the vector.
2400: Not Collective
2402: Input Parameter:
2403: . x - the vector
2405: Output Parameters:
2406: . size - the global length of the vector
2408: Level: beginner
2410: Concepts: vector^local size
2412: .seealso: VecGetLocalSize()
2413: @*/
2414: PetscErrorCode VecGetSize(Vec x,PetscInt *size)
2415: {
2422: (*x->ops->getsize)(x,size);
2423: return(0);
2424: }
2428: /*@
2429: VecGetLocalSize - Returns the number of elements of the vector stored
2430: in local memory. This routine may be implementation dependent, so use
2431: with care.
2433: Not Collective
2435: Input Parameter:
2436: . x - the vector
2438: Output Parameter:
2439: . size - the length of the local piece of the vector
2441: Level: beginner
2443: Concepts: vector^size
2445: .seealso: VecGetSize()
2446: @*/
2447: PetscErrorCode VecGetLocalSize(Vec x,PetscInt *size)
2448: {
2455: (*x->ops->getlocalsize)(x,size);
2456: return(0);
2457: }
2461: /*@C
2462: VecGetOwnershipRange - Returns the range of indices owned by
2463: this processor, assuming that the vectors are laid out with the
2464: first n1 elements on the first processor, next n2 elements on the
2465: second, etc. For certain parallel layouts this range may not be
2466: well defined.
2468: Not Collective
2470: Input Parameter:
2471: . x - the vector
2473: Output Parameters:
2474: + low - the first local element, pass in PETSC_NULL if not interested
2475: - high - one more than the last local element, pass in PETSC_NULL if not interested
2477: Note:
2478: The high argument is one more than the last element stored locally.
2480: Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL
2482: Level: beginner
2484: Concepts: ownership^of vectors
2485: Concepts: vector^ownership of elements
2487: @*/
2488: PetscErrorCode VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
2489: {
2497: PetscMapGetLocalRange(x->map,low,high);
2498: return(0);
2499: }
2503: /*@C
2504: VecGetPetscMap - Returns the map associated with the vector
2506: Not Collective
2508: Input Parameter:
2509: . x - the vector
2511: Output Parameters:
2512: . map - the map
2514: Level: developer
2516: @*/
2517: PetscErrorCode VecGetPetscMap(Vec x,PetscMap *map)
2518: {
2523: *map = x->map;
2524: return(0);
2525: }
2529: /*@
2530: VecSetOption - Sets an option for controling a vector's behavior.
2532: Collective on Vec
2534: Input Parameter:
2535: + x - the vector
2536: - op - the option
2538: Supported Options:
2539: + VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
2540: entries destined to be stored on a seperate processor. This can be used
2541: to eliminate the global reduction in the VecAssemblyXXXX() if you know
2542: that you have only used VecSetValues() to set local elements
2543: - VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.
2545: Level: intermediate
2547: @*/
2548: PetscErrorCode VecSetOption(Vec x,VecOption op)
2549: {
2555: if (x->ops->setoption) {
2556: (*x->ops->setoption)(x,op);
2557: }
2558: return(0);
2559: }
2563: /* Default routines for obtaining and releasing; */
2564: /* may be used by any implementation */
2565: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
2566: {
2568: PetscInt i;
2573: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2574: PetscMalloc(m*sizeof(Vec*),V);
2575: for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2576: return(0);
2577: }
2581: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
2582: {
2584: PetscInt i;
2588: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2589: for (i=0; i<m; i++) {VecDestroy(v[i]);}
2590: PetscFree(v);
2591: return(0);
2592: }
2596: /*@
2597: VecPlaceArray - Allows one to replace the array in a vector with an
2598: array provided by the user. This is useful to avoid copying an array
2599: into a vector.
2601: Not Collective
2603: Input Parameters:
2604: + vec - the vector
2605: - array - the array
2607: Notes:
2608: You can return to the original array with a call to VecResetArray()
2610: Level: developer
2612: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
2614: @*/
2615: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
2616: {
2623: if (vec->ops->placearray) {
2624: (*vec->ops->placearray)(vec,array);
2625: } else {
2626: SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
2627: }
2628: PetscObjectIncreaseState((PetscObject)vec);
2629: return(0);
2630: }
2634: /*@
2635: VecResetArray - Resets a vector to use its default memory. Call this
2636: after the use of VecPlaceArray().
2638: Not Collective
2640: Input Parameters:
2641: . vec - the vector
2643: Level: developer
2645: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()
2647: @*/
2648: PetscErrorCode VecResetArray(Vec vec)
2649: {
2655: if (vec->ops->resetarray) {
2656: (*vec->ops->resetarray)(vec);
2657: } else {
2658: SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
2659: }
2660: PetscObjectIncreaseState((PetscObject)vec);
2661: return(0);
2662: }
2666: /*@C
2667: VecReplaceArray - Allows one to replace the array in a vector with an
2668: array provided by the user. This is useful to avoid copying an array
2669: into a vector.
2671: Not Collective
2673: Input Parameters:
2674: + vec - the vector
2675: - array - the array
2677: Notes:
2678: This permanently replaces the array and frees the memory associated
2679: with the old array.
2681: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2682: freed by the user. It will be freed when the vector is destroy.
2684: Not supported from Fortran
2686: Level: developer
2688: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
2690: @*/
2691: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
2692: {
2698: if (vec->ops->replacearray) {
2699: (*vec->ops->replacearray)(vec,array);
2700: } else {
2701: SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
2702: }
2703: PetscObjectIncreaseState((PetscObject)vec);
2704: return(0);
2705: }
2707: /*MC
2708: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2709: and makes them accessible via a Fortran90 pointer.
2711: Synopsis:
2712: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
2714: Collective on Vec
2716: Input Parameters:
2717: + x - a vector to mimic
2718: - n - the number of vectors to obtain
2720: Output Parameters:
2721: + y - Fortran90 pointer to the array of vectors
2722: - ierr - error code
2724: Example of Usage:
2725: .vb
2726: Vec x
2727: Vec, pointer :: y(:)
2728: ....
2729: call VecDuplicateVecsF90(x,2,y,ierr)
2730: call VecSet(alpha,y(2),ierr)
2731: call VecSet(alpha,y(2),ierr)
2732: ....
2733: call VecDestroyVecsF90(y,2,ierr)
2734: .ve
2736: Notes:
2737: Not yet supported for all F90 compilers
2739: Use VecDestroyVecsF90() to free the space.
2741: Level: beginner
2743: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
2745: M*/
2747: /*MC
2748: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2749: VecGetArrayF90().
2751: Synopsis:
2752: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2754: Not collective
2756: Input Parameters:
2757: + x - vector
2758: - xx_v - the Fortran90 pointer to the array
2760: Output Parameter:
2761: . ierr - error code
2763: Example of Usage:
2764: .vb
2765: PetscScalar, pointer :: xx_v(:)
2766: ....
2767: call VecGetArrayF90(x,xx_v,ierr)
2768: a = xx_v(3)
2769: call VecRestoreArrayF90(x,xx_v,ierr)
2770: .ve
2771:
2772: Notes:
2773: Not yet supported for all F90 compilers
2775: Level: beginner
2777: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray()
2779: M*/
2781: /*MC
2782: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
2784: Synopsis:
2785: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
2787: Input Parameters:
2788: + x - pointer to array of vector pointers
2789: - n - the number of vectors previously obtained
2791: Output Parameter:
2792: . ierr - error code
2794: Notes:
2795: Not yet supported for all F90 compilers
2797: Level: beginner
2799: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
2801: M*/
2803: /*MC
2804: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2805: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2806: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
2807: when you no longer need access to the array.
2809: Synopsis:
2810: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2812: Not Collective
2814: Input Parameter:
2815: . x - vector
2817: Output Parameters:
2818: + xx_v - the Fortran90 pointer to the array
2819: - ierr - error code
2821: Example of Usage:
2822: .vb
2823: PetscScalar, pointer :: xx_v(:)
2824: ....
2825: call VecGetArrayF90(x,xx_v,ierr)
2826: a = xx_v(3)
2827: call VecRestoreArrayF90(x,xx_v,ierr)
2828: .ve
2830: Notes:
2831: Not yet supported for all F90 compilers
2833: Level: beginner
2835: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()
2837: M*/
2841: /*@C
2842: VecLoadIntoVector - Loads a vector that has been stored in binary format
2843: with VecView().
2845: Collective on PetscViewer
2847: Input Parameters:
2848: + viewer - binary file viewer, obtained from PetscViewerBinaryOpen()
2849: - vec - vector to contain files values (must be of correct length)
2851: Level: intermediate
2853: Notes:
2854: The input file must contain the full global vector, as
2855: written by the routine VecView().
2857: Use VecLoad() to create the vector as the values are read in
2859: Notes for advanced users:
2860: Most users should not need to know the details of the binary storage
2861: format, since VecLoad() and VecView() completely hide these details.
2862: But for anyone who's interested, the standard binary matrix storage
2863: format is
2864: .vb
2865: int VEC_FILE_COOKIE
2866: int number of rows
2867: PetscScalar *values of all nonzeros
2868: .ve
2870: Note for Cray users, the int's stored in the binary file are 32 bit
2871: integers; not 64 as they are represented in the memory, so if you
2872: write your own routines to read/write these binary files from the Cray
2873: you need to adjust the integer sizes that you read in, see
2874: PetscReadBinary() and PetscWriteBinary() to see how this may be
2875: done.
2877: In addition, PETSc automatically does the byte swapping for
2878: machines that store the bytes reversed, e.g. DEC alpha, freebsd,
2879: linux, Windows and the paragon; thus if you write your own binary
2880: read/write routines you have to swap the bytes; see PetscReadBinary()
2881: and PetscWriteBinary() to see how this may be done.
2883: Concepts: vector^loading from file
2885: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
2886: @*/
2887: PetscErrorCode VecLoadIntoVector(PetscViewer viewer,Vec vec)
2888: {
2895: if (!vec->ops->loadintovector) {
2896: SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
2897: }
2898: (*vec->ops->loadintovector)(viewer,vec);
2899: PetscObjectIncreaseState((PetscObject)vec);
2900: return(0);
2901: }
2905: /*@
2906: VecReciprocal - Replaces each component of a vector by its reciprocal.
2908: Collective on Vec
2910: Input Parameter:
2911: . v - the vector
2913: Output Parameter:
2914: . v - the vector reciprocal
2916: Level: intermediate
2918: Concepts: vector^reciprocal
2920: @*/
2921: PetscErrorCode VecReciprocal(Vec vec)
2922: {
2928: if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
2929: if (!vec->ops->reciprocal) {
2930: SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
2931: }
2932: (*vec->ops->reciprocal)(vec);
2933: PetscObjectIncreaseState((PetscObject)vec);
2934: return(0);
2935: }
2939: PetscErrorCode VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2940: {
2943: /* save the native version of the viewer */
2944: if (op == VECOP_VIEW && !vec->ops->viewnative) {
2945: vec->ops->viewnative = vec->ops->view;
2946: }
2947: (((void(**)(void))vec->ops)[(int)op]) = f;
2948: return(0);
2949: }
2953: /*@
2954: VecStashSetInitialSize - sets the sizes of the vec-stash, that is
2955: used during the assembly process to store values that belong to
2956: other processors.
2958: Collective on Vec
2960: Input Parameters:
2961: + vec - the vector
2962: . size - the initial size of the stash.
2963: - bsize - the initial size of the block-stash(if used).
2965: Options Database Keys:
2966: + -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2967: - -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
2969: Level: intermediate
2971: Notes:
2972: The block-stash is used for values set with VecSetValuesBlocked() while
2973: the stash is used for values set with VecSetValues()
2975: Run with the option -log_info and look for output of the form
2976: VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2977: to determine the appropriate value, MM, to use for size and
2978: VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2979: to determine the value, BMM to use for bsize
2981: Concepts: vector^stash
2982: Concepts: stash^vector
2984: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()
2986: @*/
2987: PetscErrorCode VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
2988: {
2993: VecStashSetInitialSize_Private(&vec->stash,size);
2994: VecStashSetInitialSize_Private(&vec->bstash,bsize);
2995: return(0);
2996: }
3000: /*@
3001: VecStashView - Prints the entries in the vector stash and block stash.
3003: Collective on Vec
3005: Input Parameters:
3006: + vec - the vector
3007: - viewer - the viewer
3009: Level: advanced
3011: Concepts: vector^stash
3012: Concepts: stash^vector
3014: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()
3016: @*/
3017: PetscErrorCode VecStashView(Vec v,PetscViewer viewer)
3018: {
3020: PetscMPIInt rank;
3021: PetscInt i,j;
3022: PetscTruth match;
3023: VecStash *s;
3024: PetscScalar val;
3031: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3032: if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3033: PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3034: MPI_Comm_rank(v->comm,&rank);
3035: s = &v->bstash;
3037: /* print block stash */
3038: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
3039: for (i=0; i<s->n; i++) {
3040: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
3041: for (j=0; j<s->bs; j++) {
3042: val = s->array[i*s->bs+j];
3043: #if defined(PETSC_USE_COMPLEX)
3044: PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3045: #else
3046: PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3047: #endif
3048: }
3049: PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3050: }
3051: PetscViewerFlush(viewer);
3053: s = &v->stash;
3055: /* print basic stash */
3056: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
3057: for (i=0; i<s->n; i++) {
3058: val = s->array[i];
3059: #if defined(PETSC_USE_COMPLEX)
3060: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3061: #else
3062: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
3063: #endif
3064: }
3065: PetscViewerFlush(viewer);
3067: PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3068: return(0);
3069: }
3073: /*@C
3074: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
3075: processor's portion of the vector data. You MUST call VecRestoreArray2d()
3076: when you no longer need access to the array.
3078: Not Collective
3080: Input Parameter:
3081: + x - the vector
3082: . m - first dimension of two dimensional array
3083: . n - second dimension of two dimensional array
3084: . mstart - first index you will use in first coordinate direction (often 0)
3085: - nstart - first index in the second coordinate direction (often 0)
3087: Output Parameter:
3088: . a - location to put pointer to the array
3090: Level: beginner
3092: Notes:
3093: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3094: obtained from the corner indices obtained from DAGetGhostCorners() while for
3095: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3096: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3097:
3098: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3100: Concepts: vector^accessing local values as 2d array
3102: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3103: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3104: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3105: @*/
3106: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3107: {
3109: PetscInt i,N;
3110: PetscScalar *aa;
3116: VecGetLocalSize(x,&N);
3117: if (m*n != N) SETERRQ3(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 2d array dimensions %D by %D",N,m,n);
3118: VecGetArray(x,&aa);
3120: PetscMalloc(m*sizeof(PetscScalar*),a);
3121: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3122: *a -= mstart;
3123: return(0);
3124: }
3128: /*@C
3129: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
3131: Not Collective
3133: Input Parameters:
3134: + x - the vector
3135: . m - first dimension of two dimensional array
3136: . n - second dimension of the two dimensional array
3137: . mstart - first index you will use in first coordinate direction (often 0)
3138: . nstart - first index in the second coordinate direction (often 0)
3139: - a - location of pointer to array obtained from VecGetArray2d()
3141: Level: beginner
3143: Notes:
3144: For regular PETSc vectors this routine does not involve any copies. For
3145: any special vectors that do not store local vector data in a contiguous
3146: array, this routine will copy the data back into the underlying
3147: vector data structure from the array obtained with VecGetArray().
3149: This routine actually zeros out the a pointer.
3151: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3152: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3153: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3154: @*/
3155: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3156: {
3158: void *dummy;
3164: dummy = (void*)(*a + mstart);
3165: PetscFree(dummy);
3166: VecRestoreArray(x,PETSC_NULL);
3167: return(0);
3168: }
3172: /*@C
3173: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
3174: processor's portion of the vector data. You MUST call VecRestoreArray1d()
3175: when you no longer need access to the array.
3177: Not Collective
3179: Input Parameter:
3180: + x - the vector
3181: . m - first dimension of two dimensional array
3182: - mstart - first index you will use in first coordinate direction (often 0)
3184: Output Parameter:
3185: . a - location to put pointer to the array
3187: Level: beginner
3189: Notes:
3190: For a vector obtained from DACreateLocalVector() mstart are likely
3191: obtained from the corner indices obtained from DAGetGhostCorners() while for
3192: DACreateGlobalVector() they are the corner indices from DAGetCorners().
3193:
3194: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3196: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3197: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3198: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3199: @*/
3200: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3201: {
3203: PetscInt N;
3209: VecGetLocalSize(x,&N);
3210: if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
3211: VecGetArray(x,a);
3212: *a -= mstart;
3213: return(0);
3214: }
3218: /*@C
3219: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
3221: Not Collective
3223: Input Parameters:
3224: + x - the vector
3225: . m - first dimension of two dimensional array
3226: . mstart - first index you will use in first coordinate direction (often 0)
3227: - a - location of pointer to array obtained from VecGetArray21()
3229: Level: beginner
3231: Notes:
3232: For regular PETSc vectors this routine does not involve any copies. For
3233: any special vectors that do not store local vector data in a contiguous
3234: array, this routine will copy the data back into the underlying
3235: vector data structure from the array obtained with VecGetArray1d().
3237: This routine actually zeros out the a pointer.
3239: Concepts: vector^accessing local values as 1d array
3241: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3242: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3243: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3244: @*/
3245: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3246: {
3252: VecRestoreArray(x,PETSC_NULL);
3253: return(0);
3254: }
3258: /*@C
3259: VecConjugate - Conjugates a vector.
3261: Collective on Vec
3263: Input Parameters:
3264: . x - the vector
3266: Level: intermediate
3268: Concepts: vector^conjugate
3270: @*/
3271: PetscErrorCode VecConjugate(Vec x)
3272: {
3273: #ifdef PETSC_USE_COMPLEX
3279: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3280: (*x->ops->conjugate)(x);
3281: /* we need to copy norms here */
3282: PetscObjectIncreaseState((PetscObject)x);
3283: return(0);
3284: #else
3285: return(0);
3286: #endif
3287: }
3291: /*@C
3292: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
3293: processor's portion of the vector data. You MUST call VecRestoreArray3d()
3294: when you no longer need access to the array.
3296: Not Collective
3298: Input Parameter:
3299: + x - the vector
3300: . m - first dimension of three dimensional array
3301: . n - second dimension of three dimensional array
3302: . p - third dimension of three dimensional array
3303: . mstart - first index you will use in first coordinate direction (often 0)
3304: . nstart - first index in the second coordinate direction (often 0)
3305: - pstart - first index in the third coordinate direction (often 0)
3307: Output Parameter:
3308: . a - location to put pointer to the array
3310: Level: beginner
3312: Notes:
3313: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3314: obtained from the corner indices obtained from DAGetGhostCorners() while for
3315: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3316: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3317:
3318: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3320: Concepts: vector^accessing local values as 3d array
3322: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3323: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3324: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3325: @*/
3326: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3327: {
3329: PetscInt i,N,j;
3330: PetscScalar *aa,**b;
3336: VecGetLocalSize(x,&N);
3337: if (m*n*p != N) SETERRQ4(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 3d array dimensions %D by %D by %D",N,m,n,p);
3338: VecGetArray(x,&aa);
3340: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3341: b = (PetscScalar **)((*a) + m);
3342: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3343: for (i=0; i<m; i++) {
3344: for (j=0; j<n; j++) {
3345: b[i*n+j] = aa + i*n*p + j*p - pstart;
3346: }
3347: }
3348: *a -= mstart;
3349: return(0);
3350: }
3354: /*@C
3355: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
3357: Not Collective
3359: Input Parameters:
3360: + x - the vector
3361: . m - first dimension of three dimensional array
3362: . n - second dimension of the three dimensional array
3363: . p - third dimension of the three dimensional array
3364: . mstart - first index you will use in first coordinate direction (often 0)
3365: . nstart - first index in the second coordinate direction (often 0)
3366: . pstart - first index in the third coordinate direction (often 0)
3367: - a - location of pointer to array obtained from VecGetArray3d()
3369: Level: beginner
3371: Notes:
3372: For regular PETSc vectors this routine does not involve any copies. For
3373: any special vectors that do not store local vector data in a contiguous
3374: array, this routine will copy the data back into the underlying
3375: vector data structure from the array obtained with VecGetArray().
3377: This routine actually zeros out the a pointer.
3379: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3380: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3381: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3382: @*/
3383: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3384: {
3386: void *dummy;
3392: dummy = (void*)(*a + mstart);
3393: PetscFree(dummy);
3394: VecRestoreArray(x,PETSC_NULL);
3395: return(0);
3396: }
3398: EXTERN PetscErrorCode VecStashGetInfo_Private(VecStash*,PetscInt*,PetscInt*);
3401: /*@
3402: VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
3403: to be communicated to other processors during the VecAssemblyBegin/End() process
3405: Not collective
3407: Input Parameter:
3408: . vec - the vector
3410: Output Parameters:
3411: + nstash - the size of the stash
3412: . reallocs - the number of additional mallocs incurred.
3413: . bnstash - the size of the block stash
3414: - breallocs - the number of additional mallocs incurred.in the block stash
3415:
3416: Level: advanced
3418: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
3419:
3420: @*/
3421: PetscErrorCode VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
3422: {
3425: VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
3426: VecStashGetInfo_Private(&vec->bstash,nstash,reallocs);
3427: return(0);
3428: }