Actual source code: vector.c
1: #define PETSCVEC_DLL
3: /*
4: Provides the interface functions for all vector operations.
5: These are the vector functions the user calls.
6: */
7: #include vecimpl.h
9: /* Logging support */
10: PetscCookie PETSCVEC_DLLEXPORT VEC_COOKIE = 0;
11: 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;
12: 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;
13: PetscEvent VEC_MTDot = 0, VEC_NormBarrier = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
14: PetscEvent VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0;
15: PetscEvent VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;
17: /* ugly globals for VecSetValue() and VecSetValueLocal() */
18: PetscInt PETSCVEC_DLLEXPORT VecSetValue_Row = 0;
19: PetscScalar PETSCVEC_DLLEXPORT VecSetValue_Value = 0.0;
23: /*
24: VecSetTypeFromOptions_Private - Sets the type of vector from user options. Defaults to a PETSc sequential vector on one
25: processor and a PETSc MPI vector on more than one processor.
27: Collective on Vec
29: Input Parameter:
30: . vec - The vector
32: Level: intermediate
34: .keywords: Vec, set, options, database, type
35: .seealso: VecSetFromOptions(), VecSetType()
36: */
37: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
38: {
39: PetscTruth opt;
40: const char *defaultType;
41: char typeName[256];
42: PetscMPIInt size;
46: if (vec->type_name) {
47: defaultType = vec->type_name;
48: } else {
49: MPI_Comm_size(vec->comm, &size);
50: if (size > 1) {
51: defaultType = VECMPI;
52: } else {
53: defaultType = VECSEQ;
54: }
55: }
57: if (!VecRegisterAllCalled) {
58: VecRegisterAll(PETSC_NULL);
59: }
60: PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
61: if (opt) {
62: VecSetType(vec, typeName);
63: } else {
64: VecSetType(vec, defaultType);
65: }
66: return(0);
67: }
71: /*@C
72: VecSetFromOptions - Configures the vector from the options database.
74: Collective on Vec
76: Input Parameter:
77: . vec - The vector
79: Notes: To see all options, run your program with the -help option, or consult the users manual.
80: Must be called after VecCreate() but before the vector is used.
82: Level: beginner
84: Concepts: vectors^setting options
85: Concepts: vectors^setting type
87: .keywords: Vec, set, options, database
88: .seealso: VecCreate(), VecPrintHelp(), VecSetOptionsPrefix()
89: @*/
90: PetscErrorCode PETSCVEC_DLLEXPORT VecSetFromOptions(Vec vec)
91: {
92: PetscTruth opt;
98: PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");
100: /* Handle generic vector options */
101: PetscOptionsHasName(PETSC_NULL, "-help", &opt);
102: if (opt) {
103: VecPrintHelp(vec);
104: }
106: /* Handle vector type options */
107: VecSetTypeFromOptions_Private(vec);
109: /* Handle specific vector options */
110: if (vec->ops->setfromoptions) {
111: (*vec->ops->setfromoptions)(vec);
112: }
113: PetscOptionsEnd();
115: VecViewFromOptions(vec, vec->name);
116: return(0);
117: }
121: /*@
122: VecPrintHelp - Prints some options for the Vec.
124: Input Parameter:
125: . vec - The vector
127: Options Database Keys:
128: $ -help, -h
130: Level: intermediate
132: .keywords: Vec, help
133: .seealso: VecSetFromOptions()
134: @*/
135: PetscErrorCode PETSCVEC_DLLEXPORT VecPrintHelp(Vec vec)
136: {
139: return(0);
140: }
144: /*@
145: VecSetSizes - Sets the local and global sizes, and checks to determine compatibility
147: Collective on Vec
149: Input Parameters:
150: + v - the vector
151: . n - the local size (or PETSC_DECIDE to have it set)
152: - N - the global size (or PETSC_DECIDE)
154: Notes:
155: n and N cannot be both PETSC_DECIDE
156: If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.
158: Level: intermediate
160: .seealso: VecGetSize(), PetscSplitOwnership()
161: @*/
162: PetscErrorCode PETSCVEC_DLLEXPORT VecSetSizes(Vec v, PetscInt n, PetscInt N)
163: {
166: if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
167: 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);
168: v->n = n;
169: v->N = N;
170: return(0);
171: }
175: /*@
176: VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
177: and VecSetValuesBlockedLocal().
179: Collective on Vec
181: Input Parameter:
182: + v - the vector
183: - bs - the blocksize
185: Notes:
186: All vectors obtained by VecDuplicate() inherit the same blocksize.
188: Level: advanced
190: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecGetBlockSize()
192: Concepts: block size^vectors
193: @*/
194: PetscErrorCode PETSCVEC_DLLEXPORT VecSetBlockSize(Vec v,PetscInt bs)
195: {
198: if (bs <= 0) bs = 1;
199: if (bs == v->bs) return(0);
200: if (v->bs != -1) SETERRQ2(PETSC_ERR_ARG_WRONGSTATE,"Cannot reset blocksize. Current size %D new %D",v->bs,bs);
201: if (v->N != -1 && v->N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %D %D",v->N,bs);
202: if (v->n != -1 && v->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
203: Try setting blocksize before setting the vector type",v->n,bs);
204:
205: v->bs = bs;
206: v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
207: return(0);
208: }
212: /*@
213: VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
214: and VecSetValuesBlockedLocal().
216: Collective on Vec
218: Input Parameter:
219: . v - the vector
221: Output Parameter:
222: . bs - the blocksize
224: Notes:
225: All vectors obtained by VecDuplicate() inherit the same blocksize.
227: Level: advanced
229: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecSetBlockSize()
231: Concepts: vector^block size
232: Concepts: block^vector
234: @*/
235: PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec v,PetscInt *bs)
236: {
240: *bs = v->bs;
241: return(0);
242: }
246: /*@
247: VecValid - Checks whether a vector object is valid.
249: Not Collective
251: Input Parameter:
252: . v - the object to check
254: Output Parameter:
255: flg - flag indicating vector status, either
256: PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.
258: Level: developer
260: @*/
261: PetscErrorCode PETSCVEC_DLLEXPORT VecValid(Vec v,PetscTruth *flg)
262: {
265: if (!v) *flg = PETSC_FALSE;
266: else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
267: else *flg = PETSC_TRUE;
268: return(0);
269: }
273: /*@C
274: VecSetOptionsPrefix - Sets the prefix used for searching for all
275: Vec options in the database.
277: Collective on Vec
279: Input Parameter:
280: + v - the Vec context
281: - prefix - the prefix to prepend to all option names
283: Notes:
284: A hyphen (-) must NOT be given at the beginning of the prefix name.
285: The first character of all runtime options is AUTOVECICALLY the hyphen.
287: Level: advanced
289: .keywords: Vec, set, options, prefix, database
291: .seealso: VecSetFromOptions()
292: @*/
293: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOptionsPrefix(Vec v,const char prefix[])
294: {
299: PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
300: return(0);
301: }
305: /*@C
306: VecAppendOptionsPrefix - Appends to the prefix used for searching for all
307: Vec options in the database.
309: Collective on Vec
311: Input Parameters:
312: + v - the Vec context
313: - prefix - the prefix to prepend to all option names
315: Notes:
316: A hyphen (-) must NOT be given at the beginning of the prefix name.
317: The first character of all runtime options is AUTOVECICALLY the hyphen.
319: Level: advanced
321: .keywords: Vec, append, options, prefix, database
323: .seealso: VecGetOptionsPrefix()
324: @*/
325: PetscErrorCode PETSCVEC_DLLEXPORT VecAppendOptionsPrefix(Vec v,const char prefix[])
326: {
328:
331: PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
332: return(0);
333: }
337: /*@C
338: VecGetOptionsPrefix - Sets the prefix used for searching for all
339: Vec options in the database.
341: Not Collective
343: Input Parameter:
344: . A - the Vec context
346: Output Parameter:
347: . prefix - pointer to the prefix string used
349: Notes: On the fortran side, the user should pass in a string 'prefix' of
350: sufficient length to hold the prefix.
352: Level: advanced
354: .keywords: Vec, get, options, prefix, database
356: .seealso: VecAppendOptionsPrefix()
357: @*/
358: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOptionsPrefix(Vec v,const char *prefix[])
359: {
364: PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
365: return(0);
366: }
370: /*@
371: VecSetUp - Sets up the internal vector data structures for the later use.
373: Collective on Vec
375: Input Parameters:
376: . v - the Vec context
378: Notes:
379: For basic use of the Vec classes the user need not explicitly call
380: VecSetUp(), since these actions will happen automatically.
382: Level: advanced
384: .keywords: Vec, setup
386: .seealso: VecCreate(), VecDestroy()
387: @*/
388: PetscErrorCode PETSCVEC_DLLEXPORT VecSetUp(Vec v)
389: {
394: VecSetFromOptions(v);
395: return(0);
396: }
400: /*@
401: VecDot - Computes the vector dot product.
403: Collective on Vec
405: Input Parameters:
406: . x, y - the vectors
408: Output Parameter:
409: . alpha - the dot product
411: Performance Issues:
412: + per-processor memory bandwidth
413: . interprocessor latency
414: - work load inbalance that causes certain processes to arrive much earlier than
415: others
417: Notes for Users of Complex Numbers:
418: For complex vectors, VecDot() computes
419: $ val = (x,y) = y^H x,
420: where y^H denotes the conjugate transpose of y.
422: Use VecTDot() for the indefinite form
423: $ val = (x,y) = y^T x,
424: where y^T denotes the transpose of y.
426: Level: intermediate
428: Concepts: inner product
429: Concepts: vector^inner product
431: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
432: @*/
433: PetscErrorCode PETSCVEC_DLLEXPORT VecDot(Vec x,Vec y,PetscScalar *val)
434: {
444: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
445: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
447: PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
448: (*x->ops->dot)(x,y,val);
449: PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
450: return(0);
451: }
455: /*@
456: VecNorm - Computes the vector norm.
458: Collective on Vec
460: Input Parameters:
461: + x - the vector
462: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
463: NORM_1_AND_2, which computes both norms and stores them
464: in a two element array.
466: Output Parameter:
467: . val - the norm
469: Notes:
470: $ NORM_1 denotes sum_i |x_i|
471: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
472: $ NORM_INFINITY denotes max_i |x_i|
474: Level: intermediate
476: Performance Issues:
477: + per-processor memory bandwidth
478: . interprocessor latency
479: - work load inbalance that causes certain processes to arrive much earlier than
480: others
482: Compile Option:
483: PETSC_HAVE_SLOW_BLAS_NORM2 will cause a C (loop unrolled) version of the norm to be used, rather
484: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
485: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
487: Concepts: norm
488: Concepts: vector^norm
490: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(),
491: VecNormBegin(), VecNormEnd()
493: @*/
494: PetscErrorCode PETSCVEC_DLLEXPORT VecNorm(Vec x,NormType type,PetscReal *val)
495: {
496: PetscTruth flg;
498: PetscInt type_id;
505: /*
506: * Cached data?
507: */
508: if (type!=NORM_1_AND_2) {
509: VecNormComposedDataID(type,&type_id);
510: PetscObjectComposedDataGetReal((PetscObject)x,type_id,*val,flg);
511: if (flg) return(0);
512: }
513:
515: PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
516: (*x->ops->norm)(x,type,val);
517: PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);
519: if (type!=NORM_1_AND_2) {
520: PetscObjectComposedDataSetReal((PetscObject)x,type_id,*val);
521: }
523: return(0);
524: }
528: PetscErrorCode PETSCVEC_DLLEXPORT VecNormComposedDataID(NormType type,PetscInt *type_id)
529: {
530: static PetscInt id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
531: PetscErrorCode ierr;
534: switch (type) {
535: case NORM_1 :
536: if (id_norm1==-1) {
537: PetscObjectComposedDataRegister(&id_norm1);}
538: *type_id = id_norm1; break;
539: case NORM_2 :
540: if (id_norm2==-1) {
541: PetscObjectComposedDataRegister(&id_norm2);}
542: *type_id = id_norm2; break;
543: case NORM_1_AND_2 :
544: /* we don't handle this one yet */
545: if (id_norm1==-1) {
546: PetscObjectComposedDataRegister(&id_norm1);}
547: if (id_norm2==-1) {
548: PetscObjectComposedDataRegister(&id_norm2);}
549: *type_id = id_norm12; break;
550: case NORM_INFINITY :
551: if (id_normInf==-1) {
552: PetscObjectComposedDataRegister(&id_normInf);}
553: *type_id = id_normInf; break;
554: case NORM_FROBENIUS :
555: if (id_normF==-1) {
556: PetscObjectComposedDataRegister(&id_normF);}
557: *type_id = id_normF; break;
558: }
559: return(0);
560: }
564: /*@
565: VecNormalize - Normalizes a vector by 2-norm.
567: Collective on Vec
569: Input Parameters:
570: + x - the vector
572: Output Parameter:
573: . x - the normalized vector
574: - val - the vector norm before normalization
576: Level: intermediate
578: Concepts: vector^normalizing
579: Concepts: normalizing^vector
581: @*/
582: PetscErrorCode PETSCVEC_DLLEXPORT VecNormalize(Vec x,PetscReal *val)
583: {
590: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
591: VecNorm(x,NORM_2,val);
592: if (!*val) {
593: PetscLogInfo((x,"VecNormalize:Vector of zero norm can not be normalized; Returning only the zero norm\n"));
594: } else {
595: PetscScalar tmp = 1.0/(*val);
596: VecScale(x,tmp);
597: }
599: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
600: return(0);
601: }
605: /*@C
606: VecMax - Determines the maximum vector component and its location.
608: Collective on Vec
610: Input Parameter:
611: . x - the vector
613: Output Parameters:
614: + val - the maximum component
615: - p - the location of val
617: Notes:
618: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
620: Level: intermediate
622: Concepts: maximum^of vector
623: Concepts: vector^maximum value
625: .seealso: VecNorm(), VecMin()
626: @*/
627: PetscErrorCode PETSCVEC_DLLEXPORT VecMax(Vec x,PetscInt *p,PetscReal *val)
628: {
635: PetscLogEventBegin(VEC_Max,x,0,0,0);
636: (*x->ops->max)(x,p,val);
637: PetscLogEventEnd(VEC_Max,x,0,0,0);
638: return(0);
639: }
643: /*@
644: VecMin - Determines the minimum vector component and its location.
646: Collective on Vec
648: Input Parameters:
649: . x - the vector
651: Output Parameter:
652: + val - the minimum component
653: - p - the location of val
655: Level: intermediate
657: Notes:
658: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
660: Concepts: minimum^of vector
661: Concepts: vector^minimum entry
663: .seealso: VecMax()
664: @*/
665: PetscErrorCode PETSCVEC_DLLEXPORT VecMin(Vec x,PetscInt *p,PetscReal *val)
666: {
673: PetscLogEventBegin(VEC_Min,x,0,0,0);
674: (*x->ops->min)(x,p,val);
675: PetscLogEventEnd(VEC_Min,x,0,0,0);
676: return(0);
677: }
681: /*@
682: VecTDot - Computes an indefinite vector dot product. That is, this
683: routine does NOT use the complex conjugate.
685: Collective on Vec
687: Input Parameters:
688: . x, y - the vectors
690: Output Parameter:
691: . val - the dot product
693: Notes for Users of Complex Numbers:
694: For complex vectors, VecTDot() computes the indefinite form
695: $ val = (x,y) = y^T x,
696: where y^T denotes the transpose of y.
698: Use VecDot() for the inner product
699: $ val = (x,y) = y^H x,
700: where y^H denotes the conjugate transpose of y.
702: Level: intermediate
704: Concepts: inner product^non-Hermitian
705: Concepts: vector^inner product
706: Concepts: non-Hermitian inner product
708: .seealso: VecDot(), VecMTDot()
709: @*/
710: PetscErrorCode PETSCVEC_DLLEXPORT VecTDot(Vec x,Vec y,PetscScalar *val)
711: {
721: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
722: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
724: PetscLogEventBegin(VEC_TDot,x,y,0,0);
725: (*x->ops->tdot)(x,y,val);
726: PetscLogEventEnd(VEC_TDot,x,y,0,0);
727: return(0);
728: }
732: /*@
733: VecScale - Scales a vector.
735: Collective on Vec
737: Input Parameters:
738: + x - the vector
739: - alpha - the scalar
741: Output Parameter:
742: . x - the scaled vector
744: Note:
745: For a vector with n components, VecScale() computes
746: $ x[i] = alpha * x[i], for i=1,...,n.
748: Level: intermediate
750: Concepts: vector^scaling
751: Concepts: scaling^vector
753: @*/
754: PetscErrorCode PETSCVEC_DLLEXPORT VecScale (Vec x, PetscScalar alpha)
755: {
756: PetscReal scale,norm1=0.0,norm2=0.0,normInf=0.0,normF=0.0;
757: PetscTruth flg1,flg2,flgInf,flgF;
759: PetscInt type_id1,type_id2,type_idInf,type_idF;
764: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
765: PetscLogEventBegin(VEC_Scale,x,0,0,0);
766: (*x->ops->scale)(x,alpha);
768: /*
769: * Update cached data
770: */
771: /* see if we have cached norms */
772: /* 1 */
773: VecNormComposedDataID(NORM_1,&type_id1);
774: PetscObjectComposedDataGetReal((PetscObject)x,type_id1,norm1,flg1);
775: /* 2 */
776: VecNormComposedDataID(NORM_2,&type_id2);
777: PetscObjectComposedDataGetReal((PetscObject)x,type_id2,norm2,flg2);
778: /* inf */
779: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
780: PetscObjectComposedDataGetReal((PetscObject)x,type_idInf,normInf,flgInf);
781: /* frobenius */
782: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
783: PetscObjectComposedDataGetReal((PetscObject)x,type_idF,normF,flgF);
785: /* in general we consider this object touched */
786: PetscObjectStateIncrease((PetscObject)x);
788: /* however, norms can be simply updated */
789: scale = PetscAbsScalar(alpha);
790: /* 1 */
791: if (flg1) {
792: PetscObjectComposedDataSetReal((PetscObject)x,type_id1,scale*norm1);
793: }
794: /* 2 */
795: if (flg2) {
796: PetscObjectComposedDataSetReal((PetscObject)x,type_id2,scale*norm2);
797: }
798: /* inf */
799: if (flgInf) {
800: PetscObjectComposedDataSetReal((PetscObject)x,type_idInf,scale*normInf);
801: }
802: /* frobenius */
803: if (flgF) {
804: PetscObjectComposedDataSetReal((PetscObject)x,type_idF,scale*normF);
805: }
807: PetscLogEventEnd(VEC_Scale,x,0,0,0);
808: return(0);
809: }
813: /*@
814: VecCopy - Copies a vector.
816: Collective on Vec
818: Input Parameter:
819: . x - the vector
821: Output Parameter:
822: . y - the copy
824: Notes:
825: For default parallel PETSc vectors, both x and y must be distributed in
826: the same manner; local copies are done.
828: Level: beginner
830: .seealso: VecDuplicate()
831: @*/
832: PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec x,Vec y)
833: {
834: PetscTruth flg;
835: PetscReal norm=0.0;
837: PetscInt type_id;
845: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
846: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
848: PetscLogEventBegin(VEC_Copy,x,y,0,0);
849: (*x->ops->copy)(x,y);
851: /*
852: * Update cached data
853: */
854: /* in general we consider this object touched */
855: PetscObjectStateIncrease((PetscObject)y);
856: /* however, norms can be simply copied over */
857: /* 2 */
858: VecNormComposedDataID(NORM_2,&type_id);
859: PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
860: if (flg) {
861: PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
862: }
863: /* 1 */
864: VecNormComposedDataID(NORM_1,&type_id);
865: PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
866: if (flg) {
867: PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
868: }
869: /* inf */
870: VecNormComposedDataID(NORM_INFINITY,&type_id);
871: PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
872: if (flg) {
873: PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
874: }
875: /* frobenius */
876: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
877: PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
878: if (flg) {
879: PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
880: }
882: PetscLogEventEnd(VEC_Copy,x,y,0,0);
883: return(0);
884: }
888: /*@
889: VecSet - Sets all components of a vector to a single scalar value.
891: Collective on Vec
893: Input Parameters:
894: + x - the vector
895: - alpha - the scalar
897: Output Parameter:
898: . x - the vector
900: Note:
901: For a vector of dimension n, VecSet() computes
902: $ x[i] = alpha, for i=1,...,n,
903: so that all vector entries then equal the identical
904: scalar value, alpha. Use the more general routine
905: VecSetValues() to set different vector entries.
907: You CANNOT call this after you have called VecSetValues() but before you call
908: VecAssemblyBegin/End().
910: Level: beginner
912: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
914: Concepts: vector^setting to constant
916: @*/
917: PetscErrorCode PETSCVEC_DLLEXPORT VecSet(Vec x,PetscScalar alpha)
918: {
919: PetscReal val;
921: PetscInt type_id;
926: 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()");
927: #if defined (PETSC_USE_DEBUG)
928: {
929: PetscReal alpha_local,alpha_max;
930: alpha_local = PetscAbsScalar(alpha);
931: MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,x->comm);
932: if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
933: }
934: #endif
936: PetscLogEventBegin(VEC_Set,x,0,0,0);
937: (*x->ops->set)(x,alpha);
938: PetscLogEventEnd(VEC_Set,x,0,0,0);
940: /*
941: * Update cached data
942: */
943: /* in general we consider this object touched */
944: PetscObjectStateIncrease((PetscObject)x);
945: /* however, norms can be simply set */
946: /* 1 */
947: val = PetscAbsScalar(alpha);
948: VecNormComposedDataID(NORM_1,&type_id);
949: PetscObjectComposedDataSetReal((PetscObject)x,type_id,x->N * val);
950: /* inf */
951: VecNormComposedDataID(NORM_INFINITY,&type_id);
952: PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);
953: /* 2 */
954: val = sqrt((double)x->N) * val;
955: VecNormComposedDataID(NORM_2,&type_id);
956: PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);
957: /* frobenius */
958: VecNormComposedDataID(NORM_FROBENIUS,&type_id);
959: PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);
961: return(0);
962: }
966: /*@C
967: VecSetRandom - Sets all components of a vector to random numbers.
969: Collective on Vec
971: Input Parameters:
972: + x - the vector
973: - rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
974: it will create one internally.
976: Output Parameter:
977: . x - the vector
979: Example of Usage:
980: .vb
981: PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
982: VecSetRandom(x,rctx);
983: PetscRandomDestroy(rctx);
984: .ve
986: Level: intermediate
988: Concepts: vector^setting to random
989: Concepts: random^vector
991: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
992: @*/
993: PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec x,PetscRandom rctx)
994: {
996: PetscRandom randObj = PETSC_NULL;
1002: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1004: if (!rctx) {
1005: MPI_Comm comm;
1006: PetscObjectGetComm((PetscObject)x,&comm);
1007: PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
1008: rctx = randObj;
1009: }
1011: PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1012: (*x->ops->setrandom)(x,rctx);
1013: PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
1014:
1015: if (randObj) {
1016: PetscRandomDestroy(randObj);
1017: }
1018: PetscObjectStateIncrease((PetscObject)x);
1019: return(0);
1020: }
1024: /*@
1025: VecAXPY - Computes y = alpha x + y.
1027: Collective on Vec
1029: Input Parameters:
1030: + alpha - the scalar
1031: - x, y - the vectors
1033: Output Parameter:
1034: . y - output vector
1036: Level: intermediate
1038: Concepts: vector^BLAS
1039: Concepts: BLAS
1041: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
1042: @*/
1043: PetscErrorCode PETSCVEC_DLLEXPORT VecAXPY(Vec y,PetscScalar alpha,Vec x)
1044: {
1053: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1054: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1056: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
1057: (*y->ops->axpy)(y,alpha,x);
1058: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
1059: PetscObjectStateIncrease((PetscObject)y);
1060: return(0);
1061: }
1065: /*@
1066: VecAXPBY - Computes y = alpha x + beta y.
1068: Collective on Vec
1070: Input Parameters:
1071: + alpha,beta - the scalars
1072: - x, y - the vectors
1074: Output Parameter:
1075: . y - output vector
1077: Level: intermediate
1079: Concepts: BLAS
1080: Concepts: vector^BLAS
1082: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
1083: @*/
1084: PetscErrorCode PETSCVEC_DLLEXPORT VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
1085: {
1094: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1095: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1097: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
1098: (*y->ops->axpby)(y,alpha,beta,x);
1099: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
1100: PetscObjectStateIncrease((PetscObject)y);
1101: return(0);
1102: }
1106: /*@
1107: VecAYPX - Computes y = x + alpha y.
1109: Collective on Vec
1111: Input Parameters:
1112: + alpha - the scalar
1113: - x, y - the vectors
1115: Output Parameter:
1116: . y - output vector
1118: Level: intermediate
1120: Concepts: vector^BLAS
1121: Concepts: BLAS
1123: .seealso: VecAXPY(), VecWAXPY()
1124: @*/
1125: PetscErrorCode PETSCVEC_DLLEXPORT VecAYPX(Vec y,PetscScalar alpha,Vec x)
1126: {
1135: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1136: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1138: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1139: (*y->ops->aypx)(y,alpha,x);
1140: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1141: PetscObjectStateIncrease((PetscObject)y);
1142: return(0);
1143: }
1147: /*@
1148: VecSwap - Swaps the vectors x and y.
1150: Collective on Vec
1152: Input Parameters:
1153: . x, y - the vectors
1155: Level: advanced
1157: Concepts: vector^swapping values
1159: @*/
1160: PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec x,Vec y)
1161: {
1162: PetscReal norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1163: PetscReal norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1164: PetscTruth flg1x,flg2x,flgInfx,flgFx;
1165: PetscTruth flg1y,flg2y,flgInfy,flgFy;
1166: PetscInt type_id1,type_id2,type_idInf,type_idF;
1175: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1176: if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1177: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1178: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1180: PetscLogEventBegin(VEC_Swap,x,y,0,0);
1182: /* See if we have cached norms */
1183: /* 1 */
1184: VecNormComposedDataID(NORM_1,&type_id1);
1185: PetscObjectComposedDataGetReal((PetscObject)x,type_id1,norm1x,flg1x);
1186: PetscObjectComposedDataGetReal((PetscObject)y,type_id1,norm1y,flg1y);
1187: /* 2 */
1188: VecNormComposedDataID(NORM_2,&type_id2);
1189: PetscObjectComposedDataGetReal((PetscObject)x,type_id2,norm2x,flg2x);
1190: PetscObjectComposedDataGetReal((PetscObject)y,type_id2,norm2y,flg2y);
1191: /* inf */
1192: VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1193: PetscObjectComposedDataGetReal((PetscObject)x,type_idInf,normInfx,flgInfx);
1194: PetscObjectComposedDataGetReal((PetscObject)y,type_idInf,normInfy,flgInfy);
1195: /* frobenius */
1196: VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1197: PetscObjectComposedDataGetReal((PetscObject)x,type_idF,normFx,flgFx);
1198: PetscObjectComposedDataGetReal((PetscObject)y,type_idF,normFy,flgFy);
1200: /* Do the actual swap */
1201: (*x->ops->swap)(x,y);
1202: PetscObjectStateIncrease((PetscObject)x);
1203: PetscObjectStateIncrease((PetscObject)y);
1205: /* Swap any cached norms */
1206: /* 1 */
1207: if (flg1x) {
1208: PetscObjectComposedDataSetReal((PetscObject)y,type_id1,norm1x);
1209: }
1210: if (flg1y) {
1211: PetscObjectComposedDataSetReal((PetscObject)x,type_id1,norm1y);
1212: }
1213: /* 2 */
1214: if (flg2x) {
1215: PetscObjectComposedDataSetReal((PetscObject)y,type_id2,norm2x);
1216: }
1217: if (flg2y) {
1218: PetscObjectComposedDataSetReal((PetscObject)x,type_id2,norm2y);
1219: }
1220: /* inf */
1221: if (flgInfx) {
1222: PetscObjectComposedDataSetReal((PetscObject)y,type_idInf,normInfx);
1223: }
1224: if (flgInfy) {
1225: PetscObjectComposedDataSetReal((PetscObject)x,type_idInf,normInfy);
1226: }
1227: /* frobenius */
1228: if (flgFx) {
1229: PetscObjectComposedDataSetReal((PetscObject)y,type_idF,normFx);
1230: }
1231: if (flgFy) {
1232: PetscObjectComposedDataSetReal((PetscObject)x,type_idF,normFy);
1233: }
1235: PetscLogEventEnd(VEC_Swap,x,y,0,0);
1237: return(0);
1238: }
1242: /*@
1243: VecWAXPY - Computes w = alpha x + y.
1245: Collective on Vec
1247: Input Parameters:
1248: + alpha - the scalar
1249: - x, y - the vectors
1251: Output Parameter:
1252: . w - the result
1254: Level: intermediate
1256: Concepts: vector^BLAS
1257: Concepts: BLAS
1259: .seealso: VecAXPY(), VecAYPX()
1260: @*/
1261: PetscErrorCode PETSCVEC_DLLEXPORT VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
1262: {
1274: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1275: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1277: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1278: (*w->ops->waxpy)(w,alpha,x,y);
1279: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1280: PetscObjectStateIncrease((PetscObject)w);
1281: return(0);
1282: }
1286: /*@
1287: VecPointwiseMult - Computes the componentwise multiplication w = x*y.
1289: Collective on Vec
1291: Input Parameters:
1292: . x, y - the vectors
1294: Output Parameter:
1295: . w - the result
1297: Level: advanced
1299: Notes: any subset of the x, y, and w may be the same vector.
1301: Concepts: vector^pointwise multiply
1303: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1304: @*/
1305: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMult(Vec w, Vec x,Vec y)
1306: {
1318: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1319: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1321: PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1322: (*w->ops->pointwisemult)(w,x,y);
1323: PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1324: PetscObjectStateIncrease((PetscObject)w);
1325: return(0);
1326: }
1330: /*@
1331: VecPointwiseMax - Computes the componentwise maximum w_i = max(x_i, y_i).
1333: Collective on Vec
1335: Input Parameters:
1336: . x, y - the vectors
1338: Output Parameter:
1339: . w - the result
1341: Level: advanced
1343: Notes: any subset of the x, y, and w may be the same vector.
1344: For complex numbers compares only the real part
1346: Concepts: vector^pointwise multiply
1348: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1349: @*/
1350: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMax(Vec w,Vec x,Vec y)
1351: {
1363: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1364: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1366: (*w->ops->pointwisemax)(w,x,y);
1367: PetscObjectStateIncrease((PetscObject)w);
1368: return(0);
1369: }
1374: /*@
1375: VecPointwiseMin - Computes the componentwise minimum w_i = min(x_i, y_i).
1377: Collective on Vec
1379: Input Parameters:
1380: . x, y - the vectors
1382: Output Parameter:
1383: . w - the result
1385: Level: advanced
1387: Notes: any subset of the x, y, and w may be the same vector.
1388: For complex numbers compares only the real part
1390: Concepts: vector^pointwise multiply
1392: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1393: @*/
1394: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMin(Vec w,Vec x,Vec y)
1395: {
1407: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1408: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1410: (*w->ops->pointwisemin)(w,x,y);
1411: PetscObjectStateIncrease((PetscObject)w);
1412: return(0);
1413: }
1417: /*@
1418: VecPointwiseMaxAbs - Computes the componentwise maximum of the absolute values w_i = max(abs(x_i), abs(y_i)).
1420: Collective on Vec
1422: Input Parameters:
1423: . x, y - the vectors
1425: Output Parameter:
1426: . w - the result
1428: Level: advanced
1430: Notes: any subset of the x, y, and w may be the same vector.
1432: Concepts: vector^pointwise multiply
1434: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
1435: @*/
1436: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
1437: {
1449: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1450: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1452: (*w->ops->pointwisemaxabs)(w,x,y);
1453: PetscObjectStateIncrease((PetscObject)w);
1454: return(0);
1455: }
1459: /*@
1460: VecPointwiseDivide - Computes the componentwise division w = x/y.
1462: Collective on Vec
1464: Input Parameters:
1465: . x, y - the vectors
1467: Output Parameter:
1468: . w - the result
1470: Level: advanced
1472: Notes: any subset of the x, y, and w may be the same vector.
1474: Concepts: vector^pointwise divide
1476: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1477: @*/
1478: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseDivide(Vec w,Vec x,Vec y)
1479: {
1491: if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1492: if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1494: (*w->ops->pointwisedivide)(w,x,y);
1495: PetscObjectStateIncrease((PetscObject)w);
1496: return(0);
1497: }
1501: /*@
1502: VecMaxPointwiseDivide - Computes the maximum of the componentwise division w = abs(x/y).
1504: Collective on Vec
1506: Input Parameters:
1507: . x, y - the vectors
1509: Output Parameter:
1510: . max - the result
1512: Level: advanced
1514: Notes: any subset of the x, y, and w may be the same vector.
1516: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
1517: @*/
1518: PetscErrorCode PETSCVEC_DLLEXPORT VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1519: {
1529: if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1530: if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1532: (*x->ops->maxpointwisedivide)(x,y,max);
1533: return(0);
1534: }
1538: /*@C
1539: VecDuplicate - Creates a new vector of the same type as an existing vector.
1541: Collective on Vec
1543: Input Parameters:
1544: . v - a vector to mimic
1546: Output Parameter:
1547: . newv - location to put new vector
1549: Notes:
1550: VecDuplicate() does not copy the vector, but rather allocates storage
1551: for the new vector. Use VecCopy() to copy a vector.
1553: Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1554: vectors.
1556: Level: beginner
1558: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1559: @*/
1560: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicate(Vec x,Vec *newv)
1561: {
1568: (*x->ops->duplicate)(x,newv);
1569: PetscObjectStateIncrease((PetscObject)*newv);
1570: return(0);
1571: }
1575: /*@C
1576: VecDestroy - Destroys a vector.
1578: Collective on Vec
1580: Input Parameters:
1581: . v - the vector
1583: Level: beginner
1585: .seealso: VecDuplicate(), VecDestroyVecs()
1586: @*/
1587: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroy(Vec v)
1588: {
1593: if (--v->refct > 0) return(0);
1594: /* destroy the internal part */
1595: if (v->ops->destroy) {
1596: (*v->ops->destroy)(v);
1597: }
1598: /* destroy the external/common part */
1599: if (v->mapping) {
1600: ISLocalToGlobalMappingDestroy(v->mapping);
1601: }
1602: if (v->bmapping) {
1603: ISLocalToGlobalMappingDestroy(v->bmapping);
1604: }
1605: if (v->map) {
1606: PetscMapDestroy(v->map);
1607: }
1608: PetscHeaderDestroy(v);
1609: return(0);
1610: }
1614: /*@C
1615: VecDuplicateVecs - Creates several vectors of the same type as an existing vector.
1617: Collective on Vec
1619: Input Parameters:
1620: + m - the number of vectors to obtain
1621: - v - a vector to mimic
1623: Output Parameter:
1624: . V - location to put pointer to array of vectors
1626: Notes:
1627: Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1628: vector.
1630: Fortran Note:
1631: The Fortran interface is slightly different from that given below, it
1632: requires one to pass in V a Vec (integer) array of size at least m.
1633: See the Fortran chapter of the users manual and petsc/src/vec/examples for details.
1635: Level: intermediate
1637: .seealso: VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1638: @*/
1639: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
1640: {
1647: (*v->ops->duplicatevecs)(v, m,V);
1648: return(0);
1649: }
1653: /*@C
1654: VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().
1656: Collective on Vec
1658: Input Parameters:
1659: + vv - pointer to array of vector pointers
1660: - m - the number of vectors previously obtained
1662: Fortran Note:
1663: The Fortran interface is slightly different from that given below.
1664: See the Fortran chapter of the users manual and
1665: petsc/src/vec/examples for details.
1667: Level: intermediate
1669: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
1670: @*/
1671: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroyVecs(Vec vv[],PetscInt m)
1672: {
1679: (*(*vv)->ops->destroyvecs)(vv,m);
1680: return(0);
1681: }
1685: /*@
1686: VecSetValues - Inserts or adds values into certain locations of a vector.
1688: Not Collective
1690: Input Parameters:
1691: + x - vector to insert in
1692: . ni - number of elements to add
1693: . ix - indices where to add
1694: . y - array of values
1695: - iora - either INSERT_VALUES or ADD_VALUES, where
1696: ADD_VALUES adds values to any existing entries, and
1697: INSERT_VALUES replaces existing entries with new values
1699: Notes:
1700: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1702: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1703: options cannot be mixed without intervening calls to the assembly
1704: routines.
1706: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1707: MUST be called after all calls to VecSetValues() have been completed.
1709: VecSetValues() uses 0-based indices in Fortran as well as in C.
1711: Negative indices may be passed in ix, these rows are
1712: simply ignored. This allows easily inserting element load matrices
1713: with homogeneous Dirchlet boundary conditions that you don't want represented
1714: in the vector.
1716: Level: beginner
1718: Concepts: vector^setting values
1720: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1721: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
1722: @*/
1723: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1724: {
1732: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1733: (*x->ops->setvalues)(x,ni,ix,y,iora);
1734: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1735: PetscObjectStateIncrease((PetscObject)x);
1736: return(0);
1737: }
1741: /*@
1742: VecGetValues - Gets values from certain locations of a vector. Currently
1743: can only get values on the same processor
1745: Collective on Vec
1746:
1747: Input Parameters:
1748: + x - vector to get values from
1749: . ni - number of elements to get
1750: - ix - indices where to get them from (in global 1d numbering)
1752: Output Parameter:
1753: . y - array of values
1755: Notes:
1756: The user provides the allocated array y; it is NOT allocated in this routine
1758: VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.
1760: VecAssemblyBegin() and VecAssemblyEnd() MUST be called before calling this
1762: VecGetValues() uses 0-based indices in Fortran as well as in C.
1764: Level: beginner
1766: Concepts: vector^getting values
1768: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
1769: VecGetValue(), VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
1770: @*/
1771: PetscErrorCode PETSCVEC_DLLEXPORT VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
1772: {
1780: (*x->ops->getvalues)(x,ni,ix,y);
1781: return(0);
1782: }
1786: /*@
1787: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
1789: Not Collective
1791: Input Parameters:
1792: + x - vector to insert in
1793: . ni - number of blocks to add
1794: . ix - indices where to add in block count, rather than element count
1795: . y - array of values
1796: - iora - either INSERT_VALUES or ADD_VALUES, where
1797: ADD_VALUES adds values to any existing entries, and
1798: INSERT_VALUES replaces existing entries with new values
1800: Notes:
1801: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
1802: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
1804: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
1805: options cannot be mixed without intervening calls to the assembly
1806: routines.
1808: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1809: MUST be called after all calls to VecSetValuesBlocked() have been completed.
1811: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
1813: Negative indices may be passed in ix, these rows are
1814: simply ignored. This allows easily inserting element load matrices
1815: with homogeneous Dirchlet boundary conditions that you don't want represented
1816: in the vector.
1818: Level: intermediate
1820: Concepts: vector^setting values blocked
1822: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1823: VecSetValues()
1824: @*/
1825: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1826: {
1834: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1835: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1836: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1837: PetscObjectStateIncrease((PetscObject)x);
1838: return(0);
1839: }
1843: /*@
1844: VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1845: by the routine VecSetValuesLocal() to allow users to insert vector entries
1846: using a local (per-processor) numbering.
1848: Collective on Vec
1850: Input Parameters:
1851: + x - vector
1852: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1854: Notes:
1855: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1857: Level: intermediate
1859: Concepts: vector^setting values with local numbering
1861: seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1862: VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1863: @*/
1864: PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1865: {
1872: if (x->mapping) {
1873: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1874: }
1876: if (x->ops->setlocaltoglobalmapping) {
1877: (*x->ops->setlocaltoglobalmapping)(x,mapping);
1878: } else {
1879: x->mapping = mapping;
1880: PetscObjectReference((PetscObject)mapping);
1881: }
1882: return(0);
1883: }
1887: /*@
1888: VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1889: by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1890: using a local (per-processor) numbering.
1892: Collective on Vec
1894: Input Parameters:
1895: + x - vector
1896: - mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()
1898: Notes:
1899: All vectors obtained with VecDuplicate() from this vector inherit the same mapping.
1901: Level: intermediate
1903: Concepts: vector^setting values blocked with local numbering
1905: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1906: VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1907: @*/
1908: PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1909: {
1916: if (x->bmapping) {
1917: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1918: }
1919: x->bmapping = mapping;
1920: PetscObjectReference((PetscObject)mapping);
1921: return(0);
1922: }
1926: /*@
1927: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1928: using a local ordering of the nodes.
1930: Not Collective
1932: Input Parameters:
1933: + x - vector to insert in
1934: . ni - number of elements to add
1935: . ix - indices where to add
1936: . y - array of values
1937: - iora - either INSERT_VALUES or ADD_VALUES, where
1938: ADD_VALUES adds values to any existing entries, and
1939: INSERT_VALUES replaces existing entries with new values
1941: Level: intermediate
1943: Notes:
1944: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
1946: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
1947: options cannot be mixed without intervening calls to the assembly
1948: routines.
1950: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1951: MUST be called after all calls to VecSetValuesLocal() have been completed.
1953: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
1955: Concepts: vector^setting values with local numbering
1957: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1958: VecSetValuesBlockedLocal()
1959: @*/
1960: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1961: {
1963: PetscInt lixp[128],*lix = lixp;
1971: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1972: if (!x->ops->setvalueslocal) {
1973: if (!x->mapping) {
1974: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1975: }
1976: if (ni > 128) {
1977: PetscMalloc(ni*sizeof(PetscInt),&lix);
1978: }
1979: ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
1980: (*x->ops->setvalues)(x,ni,lix,y,iora);
1981: if (ni > 128) {
1982: PetscFree(lix);
1983: }
1984: } else {
1985: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1986: }
1987: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1988: PetscObjectStateIncrease((PetscObject)x);
1989: return(0);
1990: }
1994: /*@
1995: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1996: using a local ordering of the nodes.
1998: Not Collective
2000: Input Parameters:
2001: + x - vector to insert in
2002: . ni - number of blocks to add
2003: . ix - indices where to add in block count, not element count
2004: . y - array of values
2005: - iora - either INSERT_VALUES or ADD_VALUES, where
2006: ADD_VALUES adds values to any existing entries, and
2007: INSERT_VALUES replaces existing entries with new values
2009: Level: intermediate
2011: Notes:
2012: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
2013: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
2015: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
2016: options cannot be mixed without intervening calls to the assembly
2017: routines.
2019: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
2020: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
2022: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
2025: Concepts: vector^setting values blocked with local numbering
2027: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
2028: VecSetLocalToGlobalMappingBlocked()
2029: @*/
2030: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
2031: {
2033: PetscInt lixp[128],*lix = lixp;
2040: if (!x->bmapping) {
2041: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
2042: }
2043: if (ni > 128) {
2044: PetscMalloc(ni*sizeof(PetscInt),&lix);
2045: }
2047: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
2048: ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
2049: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
2050: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
2051: if (ni > 128) {
2052: PetscFree(lix);
2053: }
2054: PetscObjectStateIncrease((PetscObject)x);
2055: return(0);
2056: }
2060: /*@
2061: VecAssemblyBegin - Begins assembling the vector. This routine should
2062: be called after completing all calls to VecSetValues().
2064: Collective on Vec
2066: Input Parameter:
2067: . vec - the vector
2069: Level: beginner
2071: Concepts: assembly^vectors
2073: .seealso: VecAssemblyEnd(), VecSetValues()
2074: @*/
2075: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec vec)
2076: {
2078: PetscTruth flg;
2084: PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
2085: if (flg) {
2086: VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2087: }
2089: PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
2090: if (vec->ops->assemblybegin) {
2091: (*vec->ops->assemblybegin)(vec);
2092: }
2093: PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
2094: PetscObjectStateIncrease((PetscObject)vec);
2095: return(0);
2096: }
2100: /*@
2101: VecAssemblyEnd - Completes assembling the vector. This routine should
2102: be called after VecAssemblyBegin().
2104: Collective on Vec
2106: Input Parameter:
2107: . vec - the vector
2109: Options Database Keys:
2110: + -vec_view - Prints vector in ASCII format
2111: . -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
2112: . -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
2113: . -vec_view_draw - Activates vector viewing using drawing tools
2114: . -display <name> - Sets display name (default is host)
2115: . -draw_pause <sec> - Sets number of seconds to pause after display
2116: - -vec_view_socket - Activates vector viewing using a socket
2117:
2118: Level: beginner
2120: .seealso: VecAssemblyBegin(), VecSetValues()
2121: @*/
2122: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec vec)
2123: {
2125: PetscTruth flg;
2129: PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
2131: if (vec->ops->assemblyend) {
2132: (*vec->ops->assemblyend)(vec);
2133: }
2134: PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
2135: PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
2136: PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
2137: if (flg) {
2138: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2139: }
2140: PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
2141: if (flg) {
2142: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
2143: VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2144: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
2145: }
2146: #if defined(PETSC_HAVE_MATLAB)
2147: PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
2148: if (flg) {
2149: VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
2150: }
2151: #endif
2152: #if defined(PETSC_USE_SOCKET_VIEWER)
2153: PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
2154: if (flg) {
2155: VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
2156: PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
2157: }
2158: #endif
2159: PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
2160: if (flg) {
2161: VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
2162: PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
2163: }
2164: PetscOptionsEnd();
2165: /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
2166: /* hence they should not be inside the above PetscOptionsBegin/End block. */
2167: PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
2168: if (flg) {
2169: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
2170: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
2171: }
2172: PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
2173: if (flg) {
2174: PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
2175: VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
2176: PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
2177: }
2178: return(0);
2179: }
2184: /*@C
2185: VecMTDot - Computes indefinite vector multiple dot products.
2186: That is, it does NOT use the complex conjugate.
2188: Collective on Vec
2190: Input Parameters:
2191: + nv - number of vectors
2192: . x - one vector
2193: - y - array of vectors. Note that vectors are pointers
2195: Output Parameter:
2196: . val - array of the dot products
2198: Notes for Users of Complex Numbers:
2199: For complex vectors, VecMTDot() computes the indefinite form
2200: $ val = (x,y) = y^T x,
2201: where y^T denotes the transpose of y.
2203: Use VecMDot() for the inner product
2204: $ val = (x,y) = y^H x,
2205: where y^H denotes the conjugate transpose of y.
2207: Level: intermediate
2209: Concepts: inner product^multiple
2210: Concepts: vector^multiple inner products
2212: .seealso: VecMDot(), VecTDot()
2213: @*/
2214: PetscErrorCode PETSCVEC_DLLEXPORT VecMTDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
2215: {
2226: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2227: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
2229: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
2230: (*x->ops->mtdot)(nv,x,y,val);
2231: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
2232: return(0);
2233: }
2237: /*@C
2238: VecMDot - Computes vector multiple dot products.
2240: Collective on Vec
2242: Input Parameters:
2243: + nv - number of vectors
2244: . x - one vector
2245: - y - array of vectors.
2247: Output Parameter:
2248: . val - array of the dot products
2250: Notes for Users of Complex Numbers:
2251: For complex vectors, VecMDot() computes
2252: $ val = (x,y) = y^H x,
2253: where y^H denotes the conjugate transpose of y.
2255: Use VecMTDot() for the indefinite form
2256: $ val = (x,y) = y^T x,
2257: where y^T denotes the transpose of y.
2259: Level: intermediate
2261: Concepts: inner product^multiple
2262: Concepts: vector^multiple inner products
2264: .seealso: VecMTDot(), VecDot()
2265: @*/
2266: PetscErrorCode PETSCVEC_DLLEXPORT VecMDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
2267: {
2278: if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2279: if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
2281: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
2282: (*x->ops->mdot)(nv,x,y,val);
2283: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
2284: return(0);
2285: }
2289: /*@C
2290: VecMAXPY - Computes y = y + sum alpha[j] x[j]
2292: Collective on Vec
2294: Input Parameters:
2295: + nv - number of scalars and x-vectors
2296: . alpha - array of scalars
2297: . y - one vector
2298: - x - array of vectors
2300: Level: intermediate
2302: Concepts: BLAS
2304: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2305: @*/
2306: PetscErrorCode PETSCVEC_DLLEXPORT VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec *x)
2307: {
2318: if (y->N != (*x)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2319: if (y->n != (*x)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
2321: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2322: (*y->ops->maxpy)(y,nv,alpha,x);
2323: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2324: PetscObjectStateIncrease((PetscObject)y);
2325: return(0);
2326: }
2328: /*MC
2329: VecGetArray - Returns a pointer to a contiguous array that contains this
2330: processor's portion of the vector data. For the standard PETSc
2331: vectors, VecGetArray() returns a pointer to the local data array and
2332: does not use any copies. If the underlying vector data is not stored
2333: in a contiquous array this routine will copy the data to a contiquous
2334: array and return a pointer to that. You MUST call VecRestoreArray()
2335: when you no longer need access to the array.
2337: Synopsis:
2338: PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])
2340: Not Collective
2342: Input Parameter:
2343: . x - the vector
2345: Output Parameter:
2346: . a - location to put pointer to the array
2348: Fortran Note:
2349: This routine is used differently from Fortran 77
2350: $ Vec x
2351: $ PetscScalar x_array(1)
2352: $ PetscOffset i_x
2353: $ PetscErrorCode ierr
2354: $ call VecGetArray(x,x_array,i_x,ierr)
2355: $
2356: $ Access first local entry in vector with
2357: $ value = x_array(i_x + 1)
2358: $
2359: $ ...... other code
2360: $ call VecRestoreArray(x,x_array,i_x,ierr)
2361: For Fortran 90 see VecGetArrayF90()
2363: See the Fortran chapter of the users manual and
2364: petsc/src/snes/examples/tutorials/ex5f.F for details.
2366: Level: beginner
2368: Concepts: vector^accessing local values
2370: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2371: M*/
2374: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
2375: {
2382: (*x->ops->getarray)(x,a);
2383: return(0);
2384: }
2389: /*@C
2390: VecGetArrays - Returns a pointer to the arrays in a set of vectors
2391: that were created by a call to VecDuplicateVecs(). You MUST call
2392: VecRestoreArrays() when you no longer need access to the array.
2394: Not Collective
2396: Input Parameter:
2397: + x - the vectors
2398: - n - the number of vectors
2400: Output Parameter:
2401: . a - location to put pointer to the array
2403: Fortran Note:
2404: This routine is not supported in Fortran.
2406: Level: intermediate
2408: .seealso: VecGetArray(), VecRestoreArrays()
2409: @*/
2410: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2411: {
2413: PetscInt i;
2414: PetscScalar **q;
2420: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
2421: PetscMalloc(n*sizeof(PetscScalar*),&q);
2422: for (i=0; i<n; ++i) {
2423: VecGetArray(x[i],&q[i]);
2424: }
2425: *a = q;
2426: return(0);
2427: }
2431: /*@C
2432: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2433: has been called.
2435: Not Collective
2437: Input Parameters:
2438: + x - the vector
2439: . n - the number of vectors
2440: - a - location of pointer to arrays obtained from VecGetArrays()
2442: Notes:
2443: For regular PETSc vectors this routine does not involve any copies. For
2444: any special vectors that do not store local vector data in a contiguous
2445: array, this routine will copy the data back into the underlying
2446: vector data structure from the arrays obtained with VecGetArrays().
2448: Fortran Note:
2449: This routine is not supported in Fortran.
2451: Level: intermediate
2453: .seealso: VecGetArrays(), VecRestoreArray()
2454: @*/
2455: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2456: {
2458: PetscInt i;
2459: PetscScalar **q = *a;
2466: for(i=0;i<n;++i) {
2467: VecRestoreArray(x[i],&q[i]);
2468: }
2469: PetscFree(q);
2470: return(0);
2471: }
2473: /*MC
2474: VecRestoreArray - Restores a vector after VecGetArray() has been called.
2476: Not Collective
2478: Synopsis:
2479: PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])
2481: Input Parameters:
2482: + x - the vector
2483: - a - location of pointer to array obtained from VecGetArray()
2485: Level: beginner
2487: Notes:
2488: For regular PETSc vectors this routine does not involve any copies. For
2489: any special vectors that do not store local vector data in a contiguous
2490: array, this routine will copy the data back into the underlying
2491: vector data structure from the array obtained with VecGetArray().
2493: This routine actually zeros out the a pointer. This is to prevent accidental
2494: us of the array after it has been restored. If you pass null for a it will
2495: not zero the array pointer a.
2497: Fortran Note:
2498: This routine is used differently from Fortran 77
2499: $ Vec x
2500: $ PetscScalar x_array(1)
2501: $ PetscOffset i_x
2502: $ PetscErrorCode ierr
2503: $ call VecGetArray(x,x_array,i_x,ierr)
2504: $
2505: $ Access first local entry in vector with
2506: $ value = x_array(i_x + 1)
2507: $
2508: $ ...... other code
2509: $ call VecRestoreArray(x,x_array,i_x,ierr)
2511: See the Fortran chapter of the users manual and
2512: petsc/src/snes/examples/tutorials/ex5f.F for details.
2513: For Fortran 90 see VecRestoreArrayF90()
2515: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2516: M*/
2519: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
2520: {
2527: #if defined(PETSC_USE_DEBUG)
2528: CHKMEMQ;
2529: #endif
2530: if (x->ops->restorearray) {
2531: (*x->ops->restorearray)(x,a);
2532: }
2533: PetscObjectStateIncrease((PetscObject)x);
2534: return(0);
2535: }
2537: #undef __FUNCT__
2539: /*@
2540: VecViewFromOptions - This function visualizes the vector based upon user options.
2542: Collective on Vec
2544: Input Parameters:
2545: . vec - The vector
2546: . title - The title
2548: Level: intermediate
2550: .keywords: Vec, view, options, database
2551: .seealso: VecSetFromOptions(), VecView()
2552: @*/
2553: PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec vec, char *title)
2554: {
2555: PetscViewer viewer;
2556: PetscDraw draw;
2557: PetscTruth opt;
2558: char *titleStr;
2559: char typeName[1024];
2560: char fileName[PETSC_MAX_PATH_LEN];
2561: size_t len;
2565: PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2566: if (opt) {
2567: PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2568: PetscStrlen(typeName, &len);
2569: if (len > 0) {
2570: PetscViewerCreate(vec->comm, &viewer);
2571: PetscViewerSetType(viewer, typeName);
2572: PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2573: if (opt) {
2574: PetscViewerSetFilename(viewer, fileName);
2575: } else {
2576: PetscViewerSetFilename(viewer, vec->name);
2577: }
2578: VecView(vec, viewer);
2579: PetscViewerFlush(viewer);
2580: PetscViewerDestroy(viewer);
2581: } else {
2582: VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2583: }
2584: }
2585: PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2586: if (opt) {
2587: PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2588: PetscViewerDrawGetDraw(viewer, 0, &draw);
2589: if (title) {
2590: titleStr = title;
2591: } else {
2592: PetscObjectName((PetscObject) vec);
2593: titleStr = vec->name;
2594: }
2595: PetscDrawSetTitle(draw, titleStr);
2596: VecView(vec, viewer);
2597: PetscViewerFlush(viewer);
2598: PetscDrawPause(draw);
2599: PetscViewerDestroy(viewer);
2600: }
2601: return(0);
2602: }
2606: /*@C
2607: VecView - Views a vector object.
2609: Collective on Vec
2611: Input Parameters:
2612: + v - the vector
2613: - viewer - an optional visualization context
2615: Notes:
2616: The available visualization contexts include
2617: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
2618: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2619: output where only the first processor opens
2620: the file. All other processors send their
2621: data to the first processor to print.
2623: You can change the format the vector is printed using the
2624: option PetscViewerSetFormat().
2626: The user can open alternative visualization contexts with
2627: + PetscViewerASCIIOpen() - Outputs vector to a specified file
2628: . PetscViewerBinaryOpen() - Outputs vector in binary to a
2629: specified file; corresponding input uses VecLoad()
2630: . PetscViewerDrawOpen() - Outputs vector to an X window display
2631: - PetscViewerSocketOpen() - Outputs vector to Socket viewer
2633: The user can call PetscViewerSetFormat() to specify the output
2634: format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2635: PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen). Available formats include
2636: + PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2637: . PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2638: . PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2639: - PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
2640: format common among all vector types
2642: Level: beginner
2644: Concepts: vector^printing
2645: Concepts: vector^saving to disk
2647: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2648: PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2649: PetscRealView(), PetscScalarView(), PetscIntView()
2650: @*/
2651: PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec vec,PetscViewer viewer)
2652: {
2653: PetscErrorCode ierr;
2654: PetscViewerFormat format;
2659: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
2662: if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");
2664: /*
2665: Check if default viewer has been overridden, but user request it anyways
2666: */
2667: PetscViewerGetFormat(viewer,&format);
2668: if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2669: PetscViewerPopFormat(viewer);
2670: (*vec->ops->viewnative)(vec,viewer);
2671: PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2672: } else {
2673: (*vec->ops->view)(vec,viewer);
2674: }
2675: return(0);
2676: }
2680: /*@
2681: VecGetSize - Returns the global number of elements of the vector.
2683: Not Collective
2685: Input Parameter:
2686: . x - the vector
2688: Output Parameters:
2689: . size - the global length of the vector
2691: Level: beginner
2693: Concepts: vector^local size
2695: .seealso: VecGetLocalSize()
2696: @*/
2697: PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec x,PetscInt *size)
2698: {
2705: (*x->ops->getsize)(x,size);
2706: return(0);
2707: }
2711: /*@
2712: VecGetLocalSize - Returns the number of elements of the vector stored
2713: in local memory. This routine may be implementation dependent, so use
2714: with care.
2716: Not Collective
2718: Input Parameter:
2719: . x - the vector
2721: Output Parameter:
2722: . size - the length of the local piece of the vector
2724: Level: beginner
2726: Concepts: vector^size
2728: .seealso: VecGetSize()
2729: @*/
2730: PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec x,PetscInt *size)
2731: {
2738: (*x->ops->getlocalsize)(x,size);
2739: return(0);
2740: }
2744: /*@C
2745: VecGetOwnershipRange - Returns the range of indices owned by
2746: this processor, assuming that the vectors are laid out with the
2747: first n1 elements on the first processor, next n2 elements on the
2748: second, etc. For certain parallel layouts this range may not be
2749: well defined.
2751: Not Collective
2753: Input Parameter:
2754: . x - the vector
2756: Output Parameters:
2757: + low - the first local element, pass in PETSC_NULL if not interested
2758: - high - one more than the last local element, pass in PETSC_NULL if not interested
2760: Note:
2761: The high argument is one more than the last element stored locally.
2763: Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL
2765: Level: beginner
2767: Concepts: ownership^of vectors
2768: Concepts: vector^ownership of elements
2770: @*/
2771: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
2772: {
2780: PetscMapGetLocalRange(x->map,low,high);
2781: return(0);
2782: }
2786: /*@C
2787: VecGetPetscMap - Returns the map associated with the vector
2789: Not Collective
2791: Input Parameter:
2792: . x - the vector
2794: Output Parameters:
2795: . map - the map
2797: Level: developer
2799: @*/
2800: PetscErrorCode PETSCVEC_DLLEXPORT VecGetPetscMap(Vec x,PetscMap *map)
2801: {
2806: *map = x->map;
2807: return(0);
2808: }
2812: /*@
2813: VecSetOption - Sets an option for controling a vector's behavior.
2815: Collective on Vec
2817: Input Parameter:
2818: + x - the vector
2819: - op - the option
2821: Supported Options:
2822: + VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
2823: entries destined to be stored on a seperate processor. This can be used
2824: to eliminate the global reduction in the VecAssemblyXXXX() if you know
2825: that you have only used VecSetValues() to set local elements
2826: - VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.
2828: Level: intermediate
2830: @*/
2831: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec x,VecOption op)
2832: {
2838: if (x->ops->setoption) {
2839: (*x->ops->setoption)(x,op);
2840: }
2841: return(0);
2842: }
2846: /* Default routines for obtaining and releasing; */
2847: /* may be used by any implementation */
2848: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
2849: {
2851: PetscInt i;
2856: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2857: PetscMalloc(m*sizeof(Vec*),V);
2858: for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2859: return(0);
2860: }
2864: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
2865: {
2867: PetscInt i;
2871: if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2872: for (i=0; i<m; i++) {VecDestroy(v[i]);}
2873: PetscFree(v);
2874: return(0);
2875: }
2879: /*@
2880: VecPlaceArray - Allows one to replace the array in a vector with an
2881: array provided by the user. This is useful to avoid copying an array
2882: into a vector.
2884: Not Collective
2886: Input Parameters:
2887: + vec - the vector
2888: - array - the array
2890: Notes:
2891: You can return to the original array with a call to VecResetArray()
2893: Level: developer
2895: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
2897: @*/
2898: PetscErrorCode PETSCVEC_DLLEXPORT VecPlaceArray(Vec vec,const PetscScalar array[])
2899: {
2906: if (vec->ops->placearray) {
2907: (*vec->ops->placearray)(vec,array);
2908: } else {
2909: SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
2910: }
2911: PetscObjectStateIncrease((PetscObject)vec);
2912: return(0);
2913: }
2917: /*@
2918: VecResetArray - Resets a vector to use its default memory. Call this
2919: after the use of VecPlaceArray().
2921: Not Collective
2923: Input Parameters:
2924: . vec - the vector
2926: Level: developer
2928: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()
2930: @*/
2931: PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec vec)
2932: {
2938: if (vec->ops->resetarray) {
2939: (*vec->ops->resetarray)(vec);
2940: } else {
2941: SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
2942: }
2943: PetscObjectStateIncrease((PetscObject)vec);
2944: return(0);
2945: }
2949: /*@C
2950: VecReplaceArray - Allows one to replace the array in a vector with an
2951: array provided by the user. This is useful to avoid copying an array
2952: into a vector.
2954: Not Collective
2956: Input Parameters:
2957: + vec - the vector
2958: - array - the array
2960: Notes:
2961: This permanently replaces the array and frees the memory associated
2962: with the old array.
2964: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2965: freed by the user. It will be freed when the vector is destroy.
2967: Not supported from Fortran
2969: Level: developer
2971: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
2973: @*/
2974: PetscErrorCode PETSCVEC_DLLEXPORT VecReplaceArray(Vec vec,const PetscScalar array[])
2975: {
2981: if (vec->ops->replacearray) {
2982: (*vec->ops->replacearray)(vec,array);
2983: } else {
2984: SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
2985: }
2986: PetscObjectStateIncrease((PetscObject)vec);
2987: return(0);
2988: }
2990: /*MC
2991: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2992: and makes them accessible via a Fortran90 pointer.
2994: Synopsis:
2995: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
2997: Collective on Vec
2999: Input Parameters:
3000: + x - a vector to mimic
3001: - n - the number of vectors to obtain
3003: Output Parameters:
3004: + y - Fortran90 pointer to the array of vectors
3005: - ierr - error code
3007: Example of Usage:
3008: .vb
3009: Vec x
3010: Vec, pointer :: y(:)
3011: ....
3012: call VecDuplicateVecsF90(x,2,y,ierr)
3013: call VecSet(y(2),alpha,ierr)
3014: call VecSet(y(2),alpha,ierr)
3015: ....
3016: call VecDestroyVecsF90(y,2,ierr)
3017: .ve
3019: Notes:
3020: Not yet supported for all F90 compilers
3022: Use VecDestroyVecsF90() to free the space.
3024: Level: beginner
3026: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
3028: M*/
3030: /*MC
3031: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
3032: VecGetArrayF90().
3034: Synopsis:
3035: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
3037: Not collective
3039: Input Parameters:
3040: + x - vector
3041: - xx_v - the Fortran90 pointer to the array
3043: Output Parameter:
3044: . ierr - error code
3046: Example of Usage:
3047: .vb
3048: PetscScalar, pointer :: xx_v(:)
3049: ....
3050: call VecGetArrayF90(x,xx_v,ierr)
3051: a = xx_v(3)
3052: call VecRestoreArrayF90(x,xx_v,ierr)
3053: .ve
3054:
3055: Notes:
3056: Not yet supported for all F90 compilers
3058: Level: beginner
3060: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray()
3062: M*/
3064: /*MC
3065: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
3067: Synopsis:
3068: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
3070: Input Parameters:
3071: + x - pointer to array of vector pointers
3072: - n - the number of vectors previously obtained
3074: Output Parameter:
3075: . ierr - error code
3077: Notes:
3078: Not yet supported for all F90 compilers
3080: Level: beginner
3082: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
3084: M*/
3086: /*MC
3087: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
3088: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
3089: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
3090: when you no longer need access to the array.
3092: Synopsis:
3093: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
3095: Not Collective
3097: Input Parameter:
3098: . x - vector
3100: Output Parameters:
3101: + xx_v - the Fortran90 pointer to the array
3102: - ierr - error code
3104: Example of Usage:
3105: .vb
3106: PetscScalar, pointer :: xx_v(:)
3107: ....
3108: call VecGetArrayF90(x,xx_v,ierr)
3109: a = xx_v(3)
3110: call VecRestoreArrayF90(x,xx_v,ierr)
3111: .ve
3113: Notes:
3114: Not yet supported for all F90 compilers
3116: Level: beginner
3118: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()
3120: M*/
3124: /*@C
3125: VecLoadIntoVector - Loads a vector that has been stored in binary format
3126: with VecView().
3128: Collective on PetscViewer
3130: Input Parameters:
3131: + viewer - binary file viewer, obtained from PetscViewerBinaryOpen()
3132: - vec - vector to contain files values (must be of correct length)
3134: Level: intermediate
3136: Notes:
3137: The input file must contain the full global vector, as
3138: written by the routine VecView().
3140: Use VecLoad() to create the vector as the values are read in
3142: Notes for advanced users:
3143: Most users should not need to know the details of the binary storage
3144: format, since VecLoad() and VecView() completely hide these details.
3145: But for anyone who's interested, the standard binary matrix storage
3146: format is
3147: .vb
3148: int VEC_FILE_COOKIE
3149: int number of rows
3150: PetscScalar *values of all nonzeros
3151: .ve
3153: Note for Cray users, the int's stored in the binary file are 32 bit
3154: integers; not 64 as they are represented in the memory, so if you
3155: write your own routines to read/write these binary files from the Cray
3156: you need to adjust the integer sizes that you read in, see
3157: PetscBinaryRead() and PetscBinaryWrite() to see how this may be
3158: done.
3160: In addition, PETSc automatically does the byte swapping for
3161: machines that store the bytes reversed, e.g. DEC alpha, freebsd,
3162: linux, Windows and the paragon; thus if you write your own binary
3163: read/write routines you have to swap the bytes; see PetscBinaryRead()
3164: and PetscBinaryWrite() to see how this may be done.
3166: Concepts: vector^loading from file
3168: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
3169: @*/
3170: PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer viewer,Vec vec)
3171: {
3178: if (!vec->ops->loadintovector) {
3179: SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
3180: }
3181: (*vec->ops->loadintovector)(viewer,vec);
3182: PetscObjectStateIncrease((PetscObject)vec);
3183: return(0);
3184: }
3188: /*@
3189: VecReciprocal - Replaces each component of a vector by its reciprocal.
3191: Collective on Vec
3193: Input Parameter:
3194: . v - the vector
3196: Output Parameter:
3197: . v - the vector reciprocal
3199: Level: intermediate
3201: Concepts: vector^reciprocal
3203: @*/
3204: PetscErrorCode PETSCVEC_DLLEXPORT VecReciprocal(Vec vec)
3205: {
3211: if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3212: if (!vec->ops->reciprocal) {
3213: SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
3214: }
3215: (*vec->ops->reciprocal)(vec);
3216: PetscObjectStateIncrease((PetscObject)vec);
3217: return(0);
3218: }
3222: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
3223: {
3226: /* save the native version of the viewer */
3227: if (op == VECOP_VIEW && !vec->ops->viewnative) {
3228: vec->ops->viewnative = vec->ops->view;
3229: }
3230: (((void(**)(void))vec->ops)[(int)op]) = f;
3231: return(0);
3232: }
3236: /*@
3237: VecStashSetInitialSize - sets the sizes of the vec-stash, that is
3238: used during the assembly process to store values that belong to
3239: other processors.
3241: Collective on Vec
3243: Input Parameters:
3244: + vec - the vector
3245: . size - the initial size of the stash.
3246: - bsize - the initial size of the block-stash(if used).
3248: Options Database Keys:
3249: + -vecstash_initial_size <size> or <size0,size1,...sizep-1>
3250: - -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>
3252: Level: intermediate
3254: Notes:
3255: The block-stash is used for values set with VecSetValuesBlocked() while
3256: the stash is used for values set with VecSetValues()
3258: Run with the option -log_info and look for output of the form
3259: VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
3260: to determine the appropriate value, MM, to use for size and
3261: VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
3262: to determine the value, BMM to use for bsize
3264: Concepts: vector^stash
3265: Concepts: stash^vector
3267: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()
3269: @*/
3270: PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
3271: {
3276: VecStashSetInitialSize_Private(&vec->stash,size);
3277: VecStashSetInitialSize_Private(&vec->bstash,bsize);
3278: return(0);
3279: }
3283: /*@
3284: VecStashView - Prints the entries in the vector stash and block stash.
3286: Collective on Vec
3288: Input Parameters:
3289: + vec - the vector
3290: - viewer - the viewer
3292: Level: advanced
3294: Concepts: vector^stash
3295: Concepts: stash^vector
3297: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()
3299: @*/
3300: PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec v,PetscViewer viewer)
3301: {
3303: PetscMPIInt rank;
3304: PetscInt i,j;
3305: PetscTruth match;
3306: VecStash *s;
3307: PetscScalar val;
3314: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3315: if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3316: PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3317: MPI_Comm_rank(v->comm,&rank);
3318: s = &v->bstash;
3320: /* print block stash */
3321: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
3322: for (i=0; i<s->n; i++) {
3323: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
3324: for (j=0; j<s->bs; j++) {
3325: val = s->array[i*s->bs+j];
3326: #if defined(PETSC_USE_COMPLEX)
3327: PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3328: #else
3329: PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3330: #endif
3331: }
3332: PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3333: }
3334: PetscViewerFlush(viewer);
3336: s = &v->stash;
3338: /* print basic stash */
3339: PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
3340: for (i=0; i<s->n; i++) {
3341: val = s->array[i];
3342: #if defined(PETSC_USE_COMPLEX)
3343: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3344: #else
3345: PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
3346: #endif
3347: }
3348: PetscViewerFlush(viewer);
3350: PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3351: return(0);
3352: }
3356: /*@C
3357: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
3358: processor's portion of the vector data. You MUST call VecRestoreArray2d()
3359: when you no longer need access to the array.
3361: Not Collective
3363: Input Parameter:
3364: + x - the vector
3365: . m - first dimension of two dimensional array
3366: . n - second dimension of two dimensional array
3367: . mstart - first index you will use in first coordinate direction (often 0)
3368: - nstart - first index in the second coordinate direction (often 0)
3370: Output Parameter:
3371: . a - location to put pointer to the array
3373: Level: beginner
3375: Notes:
3376: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3377: obtained from the corner indices obtained from DAGetGhostCorners() while for
3378: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3379: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3380:
3381: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3383: Concepts: vector^accessing local values as 2d array
3385: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3386: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3387: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3388: @*/
3389: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3390: {
3392: PetscInt i,N;
3393: PetscScalar *aa;
3399: VecGetLocalSize(x,&N);
3400: 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);
3401: VecGetArray(x,&aa);
3403: PetscMalloc(m*sizeof(PetscScalar*),a);
3404: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3405: *a -= mstart;
3406: return(0);
3407: }
3411: /*@C
3412: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
3414: Not Collective
3416: Input Parameters:
3417: + x - the vector
3418: . m - first dimension of two dimensional array
3419: . n - second dimension of the two dimensional array
3420: . mstart - first index you will use in first coordinate direction (often 0)
3421: . nstart - first index in the second coordinate direction (often 0)
3422: - a - location of pointer to array obtained from VecGetArray2d()
3424: Level: beginner
3426: Notes:
3427: For regular PETSc vectors this routine does not involve any copies. For
3428: any special vectors that do not store local vector data in a contiguous
3429: array, this routine will copy the data back into the underlying
3430: vector data structure from the array obtained with VecGetArray().
3432: This routine actually zeros out the a pointer.
3434: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3435: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3436: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3437: @*/
3438: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3439: {
3441: void *dummy;
3447: dummy = (void*)(*a + mstart);
3448: PetscFree(dummy);
3449: VecRestoreArray(x,PETSC_NULL);
3450: return(0);
3451: }
3455: /*@C
3456: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
3457: processor's portion of the vector data. You MUST call VecRestoreArray1d()
3458: when you no longer need access to the array.
3460: Not Collective
3462: Input Parameter:
3463: + x - the vector
3464: . m - first dimension of two dimensional array
3465: - mstart - first index you will use in first coordinate direction (often 0)
3467: Output Parameter:
3468: . a - location to put pointer to the array
3470: Level: beginner
3472: Notes:
3473: For a vector obtained from DACreateLocalVector() mstart are likely
3474: obtained from the corner indices obtained from DAGetGhostCorners() while for
3475: DACreateGlobalVector() they are the corner indices from DAGetCorners().
3476:
3477: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3479: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3480: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3481: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3482: @*/
3483: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3484: {
3486: PetscInt N;
3492: VecGetLocalSize(x,&N);
3493: if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
3494: VecGetArray(x,a);
3495: *a -= mstart;
3496: return(0);
3497: }
3501: /*@C
3502: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
3504: Not Collective
3506: Input Parameters:
3507: + x - the vector
3508: . m - first dimension of two dimensional array
3509: . mstart - first index you will use in first coordinate direction (often 0)
3510: - a - location of pointer to array obtained from VecGetArray21()
3512: Level: beginner
3514: Notes:
3515: For regular PETSc vectors this routine does not involve any copies. For
3516: any special vectors that do not store local vector data in a contiguous
3517: array, this routine will copy the data back into the underlying
3518: vector data structure from the array obtained with VecGetArray1d().
3520: This routine actually zeros out the a pointer.
3522: Concepts: vector^accessing local values as 1d array
3524: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3525: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3526: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3527: @*/
3528: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3529: {
3535: VecRestoreArray(x,PETSC_NULL);
3536: return(0);
3537: }
3541: /*@
3542: VecConjugate - Conjugates a vector.
3544: Collective on Vec
3546: Input Parameters:
3547: . x - the vector
3549: Level: intermediate
3551: Concepts: vector^conjugate
3553: @*/
3554: PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec x)
3555: {
3556: #ifdef PETSC_USE_COMPLEX
3562: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3563: (*x->ops->conjugate)(x);
3564: /* we need to copy norms here */
3565: PetscObjectStateIncrease((PetscObject)x);
3566: return(0);
3567: #else
3568: return(0);
3569: #endif
3570: }
3574: /*@C
3575: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
3576: processor's portion of the vector data. You MUST call VecRestoreArray3d()
3577: when you no longer need access to the array.
3579: Not Collective
3581: Input Parameter:
3582: + x - the vector
3583: . m - first dimension of three dimensional array
3584: . n - second dimension of three dimensional array
3585: . p - third dimension of three dimensional array
3586: . mstart - first index you will use in first coordinate direction (often 0)
3587: . nstart - first index in the second coordinate direction (often 0)
3588: - pstart - first index in the third coordinate direction (often 0)
3590: Output Parameter:
3591: . a - location to put pointer to the array
3593: Level: beginner
3595: Notes:
3596: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3597: obtained from the corner indices obtained from DAGetGhostCorners() while for
3598: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3599: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3600:
3601: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3603: Concepts: vector^accessing local values as 3d array
3605: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3606: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3607: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3608: @*/
3609: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3610: {
3612: PetscInt i,N,j;
3613: PetscScalar *aa,**b;
3619: VecGetLocalSize(x,&N);
3620: 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);
3621: VecGetArray(x,&aa);
3623: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3624: b = (PetscScalar **)((*a) + m);
3625: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3626: for (i=0; i<m; i++) {
3627: for (j=0; j<n; j++) {
3628: b[i*n+j] = aa + i*n*p + j*p - pstart;
3629: }
3630: }
3631: *a -= mstart;
3632: return(0);
3633: }
3637: /*@C
3638: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
3640: Not Collective
3642: Input Parameters:
3643: + x - the vector
3644: . m - first dimension of three dimensional array
3645: . n - second dimension of the three dimensional array
3646: . p - third dimension of the three dimensional array
3647: . mstart - first index you will use in first coordinate direction (often 0)
3648: . nstart - first index in the second coordinate direction (often 0)
3649: . pstart - first index in the third coordinate direction (often 0)
3650: - a - location of pointer to array obtained from VecGetArray3d()
3652: Level: beginner
3654: Notes:
3655: For regular PETSc vectors this routine does not involve any copies. For
3656: any special vectors that do not store local vector data in a contiguous
3657: array, this routine will copy the data back into the underlying
3658: vector data structure from the array obtained with VecGetArray().
3660: This routine actually zeros out the a pointer.
3662: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3663: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3664: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3665: @*/
3666: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3667: {
3669: void *dummy;
3675: dummy = (void*)(*a + mstart);
3676: PetscFree(dummy);
3677: VecRestoreArray(x,PETSC_NULL);
3678: return(0);
3679: }
3683: /*@C
3684: VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
3685: processor's portion of the vector data. You MUST call VecRestoreArray4d()
3686: when you no longer need access to the array.
3688: Not Collective
3690: Input Parameter:
3691: + x - the vector
3692: . m - first dimension of four dimensional array
3693: . n - second dimension of four dimensional array
3694: . p - third dimension of four dimensional array
3695: . q - fourth dimension of four dimensional array
3696: . mstart - first index you will use in first coordinate direction (often 0)
3697: . nstart - first index in the second coordinate direction (often 0)
3698: . pstart - first index in the third coordinate direction (often 0)
3699: - qstart - first index in the fourth coordinate direction (often 0)
3701: Output Parameter:
3702: . a - location to put pointer to the array
3704: Level: beginner
3706: Notes:
3707: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3708: obtained from the corner indices obtained from DAGetGhostCorners() while for
3709: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3710: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3711:
3712: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3714: Concepts: vector^accessing local values as 3d array
3716: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3717: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3718: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3719: @*/
3720: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3721: {
3723: PetscInt i,N,j,k;
3724: PetscScalar *aa,***b,**c;
3730: VecGetLocalSize(x,&N);
3731: if (m*n*p*q != N) SETERRQ5(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 4d array dimensions %D by %D by %D by %D",N,m,n,p,q);
3732: VecGetArray(x,&aa);
3734: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
3735: b = (PetscScalar ***)((*a) + m);
3736: c = (PetscScalar **)(b + m*n);
3737: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3738: for (i=0; i<m; i++) {
3739: for (j=0; j<n; j++) {
3740: b[i*n+j] = c + i*n*p + j*p - pstart;
3741: }
3742: }
3743: for (i=0; i<m; i++) {
3744: for (j=0; j<n; j++) {
3745: for (k=0; k<p; k++) {
3746: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
3747: }
3748: }
3749: }
3750: *a -= mstart;
3751: return(0);
3752: }
3756: /*@C
3757: VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.
3759: Not Collective
3761: Input Parameters:
3762: + x - the vector
3763: . m - first dimension of four dimensional array
3764: . n - second dimension of the four dimensional array
3765: . p - third dimension of the four dimensional array
3766: . q - fourth dimension of the four dimensional array
3767: . mstart - first index you will use in first coordinate direction (often 0)
3768: . nstart - first index in the second coordinate direction (often 0)
3769: . pstart - first index in the third coordinate direction (often 0)
3770: . qstart - first index in the fourth coordinate direction (often 0)
3771: - a - location of pointer to array obtained from VecGetArray4d()
3773: Level: beginner
3775: Notes:
3776: For regular PETSc vectors this routine does not involve any copies. For
3777: any special vectors that do not store local vector data in a contiguous
3778: array, this routine will copy the data back into the underlying
3779: vector data structure from the array obtained with VecGetArray().
3781: This routine actually zeros out the a pointer.
3783: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3784: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3785: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3786: @*/
3787: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3788: {
3790: void *dummy;
3796: dummy = (void*)(*a + mstart);
3797: PetscFree(dummy);
3798: VecRestoreArray(x,PETSC_NULL);
3799: return(0);
3800: }
3802: EXTERN PetscErrorCode VecStashGetInfo_Private(VecStash*,PetscInt*,PetscInt*);
3805: /*@
3806: VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
3807: to be communicated to other processors during the VecAssemblyBegin/End() process
3809: Not collective
3811: Input Parameter:
3812: . vec - the vector
3814: Output Parameters:
3815: + nstash - the size of the stash
3816: . reallocs - the number of additional mallocs incurred.
3817: . bnstash - the size of the block stash
3818: - breallocs - the number of additional mallocs incurred.in the block stash
3819:
3820: Level: advanced
3822: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
3823:
3824: @*/
3825: PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
3826: {
3829: VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
3830: VecStashGetInfo_Private(&vec->bstash,nstash,reallocs);
3831: return(0);
3832: }