Actual source code: rvector.c
1: #define PETSCVEC_DLL
3: /*
4: Provides the interface functions for vector operations that have PetscScalar/PetscReal in the signature
5: These are the vector functions the user calls.
6: */
7: #include private/vecimpl.h
10: if ((x)->map->N != (y)->map->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths"); \
11: if ((x)->map->n != (y)->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
16: /*@
17: VecMaxPointwiseDivide - Computes the maximum of the componentwise division max = max_i abs(x_i/y_i).
19: Collective on Vec
21: Input Parameters:
22: . x, y - the vectors
24: Output Parameter:
25: . max - the result
27: Level: advanced
29: Notes: any subset of the x and may be the same vector.
30: if a particular y_i is zero, it is treated as 1 in the above formula
32: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
33: @*/
34: PetscErrorCode VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
35: {
47: (*x->ops->maxpointwisedivide)(x,y,max);
48: return(0);
49: }
53: /*@
54: VecDot - Computes the vector dot product.
56: Collective on Vec
58: Input Parameters:
59: . x, y - the vectors
61: Output Parameter:
62: . val - the dot product
64: Performance Issues:
65: + per-processor memory bandwidth
66: . interprocessor latency
67: - work load inbalance that causes certain processes to arrive much earlier than
68: others
70: Notes for Users of Complex Numbers:
71: For complex vectors, VecDot() computes
72: $ val = (x,y) = y^H x,
73: where y^H denotes the conjugate transpose of y.
75: Use VecTDot() for the indefinite form
76: $ val = (x,y) = y^T x,
77: where y^T denotes the transpose of y.
79: Level: intermediate
81: Concepts: inner product
82: Concepts: vector^inner product
84: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
85: @*/
86: PetscErrorCode VecDot(Vec x,Vec y,PetscScalar *val)
87: {
99: PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,((PetscObject)x)->comm);
100: (*x->ops->dot)(x,y,val);
101: PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,((PetscObject)x)->comm);
102: return(0);
103: }
107: /*@
108: VecNorm - Computes the vector norm.
110: Collective on Vec
112: Input Parameters:
113: + x - the vector
114: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
115: NORM_1_AND_2, which computes both norms and stores them
116: in a two element array.
118: Output Parameter:
119: . val - the norm
121: Notes:
122: $ NORM_1 denotes sum_i |x_i|
123: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
124: $ NORM_INFINITY denotes max_i |x_i|
126: Level: intermediate
128: Performance Issues:
129: + per-processor memory bandwidth
130: . interprocessor latency
131: - work load inbalance that causes certain processes to arrive much earlier than
132: others
134: Compile Option:
135: PETSC_HAVE_SLOW_BLAS_NORM2 will cause a C (loop unrolled) version of the norm to be used, rather
136: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
137: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
139: Concepts: norm
140: Concepts: vector^norm
142: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNormAvailable(),
143: VecNormBegin(), VecNormEnd()
145: @*/
146: PetscErrorCode VecNorm(Vec x,NormType type,PetscReal *val)
147: {
148: PetscTruth flg;
156: /*
157: * Cached data?
158: */
159: if (type!=NORM_1_AND_2) {
160: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,flg);
161: if (flg) return(0);
162: }
164: PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,((PetscObject)x)->comm);
165: (*x->ops->norm)(x,type,val);
166: PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,((PetscObject)x)->comm);
168: if (type!=NORM_1_AND_2) {
169: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[type],*val);
170: }
171: return(0);
172: }
176: /*@
177: VecNormAvailable - Returns the vector norm if it is already known.
179: Collective on Vec
181: Input Parameters:
182: + x - the vector
183: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
184: NORM_1_AND_2, which computes both norms and stores them
185: in a two element array.
187: Output Parameter:
188: + available - PETSC_TRUE if the val returned is valid
189: - val - the norm
191: Notes:
192: $ NORM_1 denotes sum_i |x_i|
193: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
194: $ NORM_INFINITY denotes max_i |x_i|
196: Level: intermediate
198: Performance Issues:
199: + per-processor memory bandwidth
200: . interprocessor latency
201: - work load inbalance that causes certain processes to arrive much earlier than
202: others
204: Compile Option:
205: PETSC_HAVE_SLOW_BLAS_NORM2 will cause a C (loop unrolled) version of the norm to be used, rather
206: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
207: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
209: Concepts: norm
210: Concepts: vector^norm
212: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNorm()
213: VecNormBegin(), VecNormEnd()
215: @*/
216: PetscErrorCode VecNormAvailable(Vec x,NormType type,PetscTruth *available,PetscReal *val)
217: {
225: *available = PETSC_FALSE;
226: if (type!=NORM_1_AND_2) {
227: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,*available);
228: }
229: return(0);
230: }
234: /*@
235: VecNormalize - Normalizes a vector by 2-norm.
237: Collective on Vec
239: Input Parameters:
240: + x - the vector
242: Output Parameter:
243: . x - the normalized vector
244: - val - the vector norm before normalization
246: Level: intermediate
248: Concepts: vector^normalizing
249: Concepts: normalizing^vector
251: @*/
252: PetscErrorCode VecNormalize(Vec x,PetscReal *val)
253: {
255: PetscReal norm;
260: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
261: VecNorm(x,NORM_2,&norm);
262: if (norm == 0.0) {
263: PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
264: } else if (norm != 1.0) {
265: PetscScalar tmp = 1.0/norm;
266: VecScale(x,tmp);
267: }
268: if (val) *val = norm;
269: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
270: return(0);
271: }
275: /*@C
276: VecMax - Determines the maximum vector component and its location.
278: Collective on Vec
280: Input Parameter:
281: . x - the vector
283: Output Parameters:
284: + val - the maximum component
285: - p - the location of val
287: Notes:
288: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
290: Level: intermediate
292: Concepts: maximum^of vector
293: Concepts: vector^maximum value
295: .seealso: VecNorm(), VecMin()
296: @*/
297: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
298: {
305: PetscLogEventBegin(VEC_Max,x,0,0,0);
306: (*x->ops->max)(x,p,val);
307: PetscLogEventEnd(VEC_Max,x,0,0,0);
308: return(0);
309: }
313: /*@
314: VecMin - Determines the minimum vector component and its location.
316: Collective on Vec
318: Input Parameters:
319: . x - the vector
321: Output Parameter:
322: + val - the minimum component
323: - p - the location of val
325: Level: intermediate
327: Notes:
328: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
330: Concepts: minimum^of vector
331: Concepts: vector^minimum entry
333: .seealso: VecMax()
334: @*/
335: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
336: {
343: PetscLogEventBegin(VEC_Min,x,0,0,0);
344: (*x->ops->min)(x,p,val);
345: PetscLogEventEnd(VEC_Min,x,0,0,0);
346: return(0);
347: }
351: /*@
352: VecTDot - Computes an indefinite vector dot product. That is, this
353: routine does NOT use the complex conjugate.
355: Collective on Vec
357: Input Parameters:
358: . x, y - the vectors
360: Output Parameter:
361: . val - the dot product
363: Notes for Users of Complex Numbers:
364: For complex vectors, VecTDot() computes the indefinite form
365: $ val = (x,y) = y^T x,
366: where y^T denotes the transpose of y.
368: Use VecDot() for the inner product
369: $ val = (x,y) = y^H x,
370: where y^H denotes the conjugate transpose of y.
372: Level: intermediate
374: Concepts: inner product^non-Hermitian
375: Concepts: vector^inner product
376: Concepts: non-Hermitian inner product
378: .seealso: VecDot(), VecMTDot()
379: @*/
380: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
381: {
393: PetscLogEventBegin(VEC_TDot,x,y,0,0);
394: (*x->ops->tdot)(x,y,val);
395: PetscLogEventEnd(VEC_TDot,x,y,0,0);
396: return(0);
397: }
401: /*@
402: VecScale - Scales a vector.
404: Collective on Vec
406: Input Parameters:
407: + x - the vector
408: - alpha - the scalar
410: Output Parameter:
411: . x - the scaled vector
413: Note:
414: For a vector with n components, VecScale() computes
415: $ x[i] = alpha * x[i], for i=1,...,n.
417: Level: intermediate
419: Concepts: vector^scaling
420: Concepts: scaling^vector
422: @*/
423: PetscErrorCode VecScale (Vec x, PetscScalar alpha)
424: {
425: PetscReal norms[4] = {0.0,0.0,0.0, 0.0};
426: PetscTruth flgs[4];
428: PetscInt i;
433: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
434: PetscLogEventBegin(VEC_Scale,x,0,0,0);
435: if (alpha != 1.0) {
436: (*x->ops->scale)(x,alpha);
438: /*
439: * Update cached data
440: */
441: for (i=0; i<4; i++) {
442: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
443: }
445: /* in general we consider this object touched */
446: PetscObjectStateIncrease((PetscObject)x);
448: for (i=0; i<4; i++) {
449: if (flgs[i]) {
450: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
451: }
452: }
453: }
454: PetscLogEventEnd(VEC_Scale,x,0,0,0);
455: return(0);
456: }
461: /*@
462: VecSet - Sets all components of a vector to a single scalar value.
464: Collective on Vec
466: Input Parameters:
467: + x - the vector
468: - alpha - the scalar
470: Output Parameter:
471: . x - the vector
473: Note:
474: For a vector of dimension n, VecSet() computes
475: $ x[i] = alpha, for i=1,...,n,
476: so that all vector entries then equal the identical
477: scalar value, alpha. Use the more general routine
478: VecSetValues() to set different vector entries.
480: You CANNOT call this after you have called VecSetValues() but before you call
481: VecAssemblyBegin/End().
483: Level: beginner
485: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
487: Concepts: vector^setting to constant
489: @*/
490: PetscErrorCode VecSet(Vec x,PetscScalar alpha)
491: {
492: PetscReal val;
498: 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()");
499: #if defined (PETSC_USE_DEBUG)
500: {
501: PetscReal alpha_local,alpha_max;
502: alpha_local = PetscAbsScalar(alpha);
503: MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,((PetscObject)x)->comm);
504: if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
505: }
506: #endif
508: PetscLogEventBegin(VEC_Set,x,0,0,0);
509: (*x->ops->set)(x,alpha);
510: PetscLogEventEnd(VEC_Set,x,0,0,0);
512: /*
513: * Update cached data
514: */
515: /* in general we consider this object touched */
516: PetscObjectStateIncrease((PetscObject)x);
518: /* however, norms can be simply set */
519: val = PetscAbsScalar(alpha);
520: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
521: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
522: val = sqrt((double)x->map->N) * val;
523: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
524: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
525: return(0);
526: }
531: /*@
532: VecAXPY - Computes y = alpha x + y.
534: Collective on Vec
536: Input Parameters:
537: + alpha - the scalar
538: - x, y - the vectors
540: Output Parameter:
541: . y - output vector
543: Level: intermediate
545: Notes: x and y must be different vectors
547: Concepts: vector^BLAS
548: Concepts: BLAS
550: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
551: @*/
552: PetscErrorCode VecAXPY(Vec y,PetscScalar alpha,Vec x)
553: {
564: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
565: (*y->ops->axpy)(y,alpha,x);
566: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
567: PetscObjectStateIncrease((PetscObject)y);
568: return(0);
569: }
573: /*@
574: VecAXPBY - Computes y = alpha x + beta y.
576: Collective on Vec
578: Input Parameters:
579: + alpha,beta - the scalars
580: - x, y - the vectors
582: Output Parameter:
583: . y - output vector
585: Level: intermediate
587: Notes: x and y must be different vectors
589: Concepts: BLAS
590: Concepts: vector^BLAS
592: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
593: @*/
594: PetscErrorCode VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
595: {
606: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
607: (*y->ops->axpby)(y,alpha,beta,x);
608: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
609: PetscObjectStateIncrease((PetscObject)y);
610: return(0);
611: }
615: /*@
616: VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z
618: Collective on Vec
620: Input Parameters:
621: + alpha,beta, gamma - the scalars
622: - x, y, z - the vectors
624: Output Parameter:
625: . z - output vector
627: Level: intermediate
629: Notes: x, y and z must be different vectors
631: alpha = 1 or gamma = 1 are handled as special cases
633: Concepts: BLAS
634: Concepts: vector^BLAS
636: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
637: @*/
638: PetscErrorCode VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
639: {
654: PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
655: (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
656: PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
657: PetscObjectStateIncrease((PetscObject)y);
658: return(0);
659: }
663: /*@
664: VecAYPX - Computes y = x + alpha y.
666: Collective on Vec
668: Input Parameters:
669: + alpha - the scalar
670: - x, y - the vectors
672: Output Parameter:
673: . y - output vector
675: Level: intermediate
677: Notes: x and y must be different vectors
679: Concepts: vector^BLAS
680: Concepts: BLAS
682: .seealso: VecAXPY(), VecWAXPY()
683: @*/
684: PetscErrorCode VecAYPX(Vec y,PetscScalar alpha,Vec x)
685: {
694: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
695: (*y->ops->aypx)(y,alpha,x);
696: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
697: PetscObjectStateIncrease((PetscObject)y);
698: return(0);
699: }
704: /*@
705: VecWAXPY - Computes w = alpha x + y.
707: Collective on Vec
709: Input Parameters:
710: + alpha - the scalar
711: - x, y - the vectors
713: Output Parameter:
714: . w - the result
716: Level: intermediate
718: Notes: Neither the vector x or y can be the same as vector w
720: Concepts: vector^BLAS
721: Concepts: BLAS
723: .seealso: VecAXPY(), VecAYPX(), VecAXPBY()
724: @*/
725: PetscErrorCode VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
726: {
740: if (w == y) SETERRQ(PETSC_ERR_SUP,"Result vector w cannot be same as input vector y, suggest VecAXPY()");
741: if (w == x) SETERRQ(PETSC_ERR_SUP,"Result vector w cannot be same as input vector x, suggest VecAYPX()");
743: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
744: (*w->ops->waxpy)(w,alpha,x,y);
745: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
746: PetscObjectStateIncrease((PetscObject)w);
747: return(0);
748: }
753: /*@
754: VecSetValues - Inserts or adds values into certain locations of a vector.
756: Not Collective
758: Input Parameters:
759: + x - vector to insert in
760: . ni - number of elements to add
761: . ix - indices where to add
762: . y - array of values
763: - iora - either INSERT_VALUES or ADD_VALUES, where
764: ADD_VALUES adds values to any existing entries, and
765: INSERT_VALUES replaces existing entries with new values
767: Notes:
768: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
770: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
771: options cannot be mixed without intervening calls to the assembly
772: routines.
774: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
775: MUST be called after all calls to VecSetValues() have been completed.
777: VecSetValues() uses 0-based indices in Fortran as well as in C.
779: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
780: negative indices may be passed in ix. These rows are
781: simply ignored. This allows easily inserting element load matrices
782: with homogeneous Dirchlet boundary conditions that you don't want represented
783: in the vector.
785: Level: beginner
787: Concepts: vector^setting values
789: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
790: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
791: @*/
792: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
793: {
801: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
802: (*x->ops->setvalues)(x,ni,ix,y,iora);
803: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
804: PetscObjectStateIncrease((PetscObject)x);
805: return(0);
806: }
810: /*@
811: VecGetValues - Gets values from certain locations of a vector. Currently
812: can only get values on the same processor
814: Collective on Vec
815:
816: Input Parameters:
817: + x - vector to get values from
818: . ni - number of elements to get
819: - ix - indices where to get them from (in global 1d numbering)
821: Output Parameter:
822: . y - array of values
824: Notes:
825: The user provides the allocated array y; it is NOT allocated in this routine
827: VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.
829: VecAssemblyBegin() and VecAssemblyEnd() MUST be called before calling this
831: VecGetValues() uses 0-based indices in Fortran as well as in C.
833: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
834: negative indices may be passed in ix. These rows are
835: simply ignored.
837: Level: beginner
839: Concepts: vector^getting values
841: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
842: VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
843: @*/
844: PetscErrorCode VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
845: {
853: (*x->ops->getvalues)(x,ni,ix,y);
854: return(0);
855: }
859: /*@
860: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
862: Not Collective
864: Input Parameters:
865: + x - vector to insert in
866: . ni - number of blocks to add
867: . ix - indices where to add in block count, rather than element count
868: . y - array of values
869: - iora - either INSERT_VALUES or ADD_VALUES, where
870: ADD_VALUES adds values to any existing entries, and
871: INSERT_VALUES replaces existing entries with new values
873: Notes:
874: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
875: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
877: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
878: options cannot be mixed without intervening calls to the assembly
879: routines.
881: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
882: MUST be called after all calls to VecSetValuesBlocked() have been completed.
884: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
886: Negative indices may be passed in ix, these rows are
887: simply ignored. This allows easily inserting element load matrices
888: with homogeneous Dirchlet boundary conditions that you don't want represented
889: in the vector.
891: Level: intermediate
893: Concepts: vector^setting values blocked
895: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
896: VecSetValues()
897: @*/
898: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
899: {
907: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
908: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
909: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
910: PetscObjectStateIncrease((PetscObject)x);
911: return(0);
912: }
917: /*@
918: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
919: using a local ordering of the nodes.
921: Not Collective
923: Input Parameters:
924: + x - vector to insert in
925: . ni - number of elements to add
926: . ix - indices where to add
927: . y - array of values
928: - iora - either INSERT_VALUES or ADD_VALUES, where
929: ADD_VALUES adds values to any existing entries, and
930: INSERT_VALUES replaces existing entries with new values
932: Level: intermediate
934: Notes:
935: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
937: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
938: options cannot be mixed without intervening calls to the assembly
939: routines.
941: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
942: MUST be called after all calls to VecSetValuesLocal() have been completed.
944: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
946: Concepts: vector^setting values with local numbering
948: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
949: VecSetValuesBlockedLocal()
950: @*/
951: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
952: {
954: PetscInt lixp[128],*lix = lixp;
962: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
963: if (!x->ops->setvalueslocal) {
964: if (!x->mapping) {
965: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
966: }
967: if (ni > 128) {
968: PetscMalloc(ni*sizeof(PetscInt),&lix);
969: }
970: ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
971: (*x->ops->setvalues)(x,ni,lix,y,iora);
972: if (ni > 128) {
973: PetscFree(lix);
974: }
975: } else {
976: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
977: }
978: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
979: PetscObjectStateIncrease((PetscObject)x);
980: return(0);
981: }
985: /*@
986: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
987: using a local ordering of the nodes.
989: Not Collective
991: Input Parameters:
992: + x - vector to insert in
993: . ni - number of blocks to add
994: . ix - indices where to add in block count, not element count
995: . y - array of values
996: - iora - either INSERT_VALUES or ADD_VALUES, where
997: ADD_VALUES adds values to any existing entries, and
998: INSERT_VALUES replaces existing entries with new values
1000: Level: intermediate
1002: Notes:
1003: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
1004: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
1006: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1007: options cannot be mixed without intervening calls to the assembly
1008: routines.
1010: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1011: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
1013: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
1016: Concepts: vector^setting values blocked with local numbering
1018: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
1019: VecSetLocalToGlobalMappingBlock()
1020: @*/
1021: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1022: {
1024: PetscInt lixp[128],*lix = lixp;
1031: if (!x->bmapping) {
1032: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlock()");
1033: }
1034: if (ni > 128) {
1035: PetscMalloc(ni*sizeof(PetscInt),&lix);
1036: }
1038: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1039: ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
1040: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1041: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1042: if (ni > 128) {
1043: PetscFree(lix);
1044: }
1045: PetscObjectStateIncrease((PetscObject)x);
1046: return(0);
1047: }
1053: /*@
1054: VecMTDot - Computes indefinite vector multiple dot products.
1055: That is, it does NOT use the complex conjugate.
1057: Collective on Vec
1059: Input Parameters:
1060: + x - one vector
1061: . nv - number of vectors
1062: - y - array of vectors. Note that vectors are pointers
1064: Output Parameter:
1065: . val - array of the dot products
1067: Notes for Users of Complex Numbers:
1068: For complex vectors, VecMTDot() computes the indefinite form
1069: $ val = (x,y) = y^T x,
1070: where y^T denotes the transpose of y.
1072: Use VecMDot() for the inner product
1073: $ val = (x,y) = y^H x,
1074: where y^H denotes the conjugate transpose of y.
1076: Level: intermediate
1078: Concepts: inner product^multiple
1079: Concepts: vector^multiple inner products
1081: .seealso: VecMDot(), VecTDot()
1082: @*/
1083: PetscErrorCode VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1084: {
1097: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1098: (*x->ops->mtdot)(x,nv,y,val);
1099: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1100: return(0);
1101: }
1105: /*@
1106: VecMDot - Computes vector multiple dot products.
1108: Collective on Vec
1110: Input Parameters:
1111: + x - one vector
1112: . nv - number of vectors
1113: - y - array of vectors.
1115: Output Parameter:
1116: . val - array of the dot products (does not allocate the array)
1118: Notes for Users of Complex Numbers:
1119: For complex vectors, VecMDot() computes
1120: $ val = (x,y) = y^H x,
1121: where y^H denotes the conjugate transpose of y.
1123: Use VecMTDot() for the indefinite form
1124: $ val = (x,y) = y^T x,
1125: where y^T denotes the transpose of y.
1127: Level: intermediate
1129: Concepts: inner product^multiple
1130: Concepts: vector^multiple inner products
1132: .seealso: VecMTDot(), VecDot()
1133: @*/
1134: PetscErrorCode VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1135: {
1140: if (!nv) return(0);
1141: if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1150: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1151: (*x->ops->mdot)(x,nv,y,val);
1152: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1153: return(0);
1154: }
1158: /*@
1159: VecMAXPY - Computes y = y + sum alpha[j] x[j]
1161: Collective on Vec
1163: Input Parameters:
1164: + nv - number of scalars and x-vectors
1165: . alpha - array of scalars
1166: . y - one vector
1167: - x - array of vectors
1169: Level: intermediate
1171: Concepts: BLAS
1173: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1174: @*/
1175: PetscErrorCode VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1176: {
1181: if (!nv) return(0);
1182: if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1191: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1192: (*y->ops->maxpy)(y,nv,alpha,x);
1193: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1194: PetscObjectStateIncrease((PetscObject)y);
1195: return(0);
1196: }
1198: /*MC
1199: VecGetArray - Returns a pointer to a contiguous array that contains this
1200: processor's portion of the vector data. For the standard PETSc
1201: vectors, VecGetArray() returns a pointer to the local data array and
1202: does not use any copies. If the underlying vector data is not stored
1203: in a contiquous array this routine will copy the data to a contiquous
1204: array and return a pointer to that. You MUST call VecRestoreArray()
1205: when you no longer need access to the array.
1207: Synopsis:
1208: PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])
1210: Not Collective
1212: Input Parameter:
1213: . x - the vector
1215: Output Parameter:
1216: . a - location to put pointer to the array
1218: Fortran Note:
1219: This routine is used differently from Fortran 77
1220: $ Vec x
1221: $ PetscScalar x_array(1)
1222: $ PetscOffset i_x
1223: $ PetscErrorCode ierr
1224: $ call VecGetArray(x,x_array,i_x,ierr)
1225: $
1226: $ Access first local entry in vector with
1227: $ value = x_array(i_x + 1)
1228: $
1229: $ ...... other code
1230: $ call VecRestoreArray(x,x_array,i_x,ierr)
1231: For Fortran 90 see VecGetArrayF90()
1233: See the Fortran chapter of the users manual and
1234: petsc/src/snes/examples/tutorials/ex5f.F for details.
1236: Level: beginner
1238: Concepts: vector^accessing local values
1240: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1241: M*/
1244: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
1245: {
1252: (*x->ops->getarray)(x,a);
1253: return(0);
1254: }
1259: /*@C
1260: VecGetArrays - Returns a pointer to the arrays in a set of vectors
1261: that were created by a call to VecDuplicateVecs(). You MUST call
1262: VecRestoreArrays() when you no longer need access to the array.
1264: Not Collective
1266: Input Parameter:
1267: + x - the vectors
1268: - n - the number of vectors
1270: Output Parameter:
1271: . a - location to put pointer to the array
1273: Fortran Note:
1274: This routine is not supported in Fortran.
1276: Level: intermediate
1278: .seealso: VecGetArray(), VecRestoreArrays()
1279: @*/
1280: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1281: {
1283: PetscInt i;
1284: PetscScalar **q;
1290: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
1291: PetscMalloc(n*sizeof(PetscScalar*),&q);
1292: for (i=0; i<n; ++i) {
1293: VecGetArray(x[i],&q[i]);
1294: }
1295: *a = q;
1296: return(0);
1297: }
1301: /*@C
1302: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1303: has been called.
1305: Not Collective
1307: Input Parameters:
1308: + x - the vector
1309: . n - the number of vectors
1310: - a - location of pointer to arrays obtained from VecGetArrays()
1312: Notes:
1313: For regular PETSc vectors this routine does not involve any copies. For
1314: any special vectors that do not store local vector data in a contiguous
1315: array, this routine will copy the data back into the underlying
1316: vector data structure from the arrays obtained with VecGetArrays().
1318: Fortran Note:
1319: This routine is not supported in Fortran.
1321: Level: intermediate
1323: .seealso: VecGetArrays(), VecRestoreArray()
1324: @*/
1325: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1326: {
1328: PetscInt i;
1329: PetscScalar **q = *a;
1336: for(i=0;i<n;++i) {
1337: VecRestoreArray(x[i],&q[i]);
1338: }
1339: PetscFree(q);
1340: return(0);
1341: }
1343: /*MC
1344: VecRestoreArray - Restores a vector after VecGetArray() has been called.
1346: Not Collective
1348: Synopsis:
1349: PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])
1351: Input Parameters:
1352: + x - the vector
1353: - a - location of pointer to array obtained from VecGetArray()
1355: Level: beginner
1357: Notes:
1358: For regular PETSc vectors this routine does not involve any copies. For
1359: any special vectors that do not store local vector data in a contiguous
1360: array, this routine will copy the data back into the underlying
1361: vector data structure from the array obtained with VecGetArray().
1363: This routine actually zeros out the a pointer. This is to prevent accidental
1364: us of the array after it has been restored. If you pass null for a it will
1365: not zero the array pointer a.
1367: Fortran Note:
1368: This routine is used differently from Fortran 77
1369: $ Vec x
1370: $ PetscScalar x_array(1)
1371: $ PetscOffset i_x
1372: $ PetscErrorCode ierr
1373: $ call VecGetArray(x,x_array,i_x,ierr)
1374: $
1375: $ Access first local entry in vector with
1376: $ value = x_array(i_x + 1)
1377: $
1378: $ ...... other code
1379: $ call VecRestoreArray(x,x_array,i_x,ierr)
1381: See the Fortran chapter of the users manual and
1382: petsc/src/snes/examples/tutorials/ex5f.F for details.
1383: For Fortran 90 see VecRestoreArrayF90()
1385: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
1386: M*/
1389: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
1390: {
1397: #if defined(PETSC_USE_DEBUG)
1398: CHKMEMQ;
1399: #endif
1400: if (x->ops->restorearray) {
1401: (*x->ops->restorearray)(x,a);
1402: }
1403: PetscObjectStateIncrease((PetscObject)x);
1404: return(0);
1405: }
1410: /*@
1411: VecPlaceArray - Allows one to replace the array in a vector with an
1412: array provided by the user. This is useful to avoid copying an array
1413: into a vector.
1415: Not Collective
1417: Input Parameters:
1418: + vec - the vector
1419: - array - the array
1421: Notes:
1422: You can return to the original array with a call to VecResetArray()
1424: Level: developer
1426: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
1428: @*/
1429: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
1430: {
1437: if (vec->ops->placearray) {
1438: (*vec->ops->placearray)(vec,array);
1439: } else {
1440: SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
1441: }
1442: PetscObjectStateIncrease((PetscObject)vec);
1443: return(0);
1444: }
1449: /*@C
1450: VecReplaceArray - Allows one to replace the array in a vector with an
1451: array provided by the user. This is useful to avoid copying an array
1452: into a vector.
1454: Not Collective
1456: Input Parameters:
1457: + vec - the vector
1458: - array - the array
1460: Notes:
1461: This permanently replaces the array and frees the memory associated
1462: with the old array.
1464: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
1465: freed by the user. It will be freed when the vector is destroy.
1467: Not supported from Fortran
1469: Level: developer
1471: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
1473: @*/
1474: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
1475: {
1481: if (vec->ops->replacearray) {
1482: (*vec->ops->replacearray)(vec,array);
1483: } else {
1484: SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
1485: }
1486: PetscObjectStateIncrease((PetscObject)vec);
1487: return(0);
1488: }
1490: /*MC
1491: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
1492: and makes them accessible via a Fortran90 pointer.
1494: Synopsis:
1495: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
1497: Collective on Vec
1499: Input Parameters:
1500: + x - a vector to mimic
1501: - n - the number of vectors to obtain
1503: Output Parameters:
1504: + y - Fortran90 pointer to the array of vectors
1505: - ierr - error code
1507: Example of Usage:
1508: .vb
1509: Vec x
1510: Vec, pointer :: y(:)
1511: ....
1512: call VecDuplicateVecsF90(x,2,y,ierr)
1513: call VecSet(y(2),alpha,ierr)
1514: call VecSet(y(2),alpha,ierr)
1515: ....
1516: call VecDestroyVecsF90(y,2,ierr)
1517: .ve
1519: Notes:
1520: Not yet supported for all F90 compilers
1522: Use VecDestroyVecsF90() to free the space.
1524: Level: beginner
1526: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
1528: M*/
1530: /*MC
1531: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
1532: VecGetArrayF90().
1534: Synopsis:
1535: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
1537: Not collective
1539: Input Parameters:
1540: + x - vector
1541: - xx_v - the Fortran90 pointer to the array
1543: Output Parameter:
1544: . ierr - error code
1546: Example of Usage:
1547: .vb
1548: PetscScalar, pointer :: xx_v(:)
1549: ....
1550: call VecGetArrayF90(x,xx_v,ierr)
1551: a = xx_v(3)
1552: call VecRestoreArrayF90(x,xx_v,ierr)
1553: .ve
1554:
1555: Level: beginner
1557: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray(), UsingFortran
1559: M*/
1561: /*MC
1562: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
1564: Synopsis:
1565: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
1567: Input Parameters:
1568: + x - pointer to array of vector pointers
1569: - n - the number of vectors previously obtained
1571: Output Parameter:
1572: . ierr - error code
1574: Notes:
1575: Not yet supported for all F90 compilers
1577: Level: beginner
1579: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
1581: M*/
1583: /*MC
1584: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
1585: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
1586: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
1587: when you no longer need access to the array.
1589: Synopsis:
1590: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
1592: Not Collective
1594: Input Parameter:
1595: . x - vector
1597: Output Parameters:
1598: + xx_v - the Fortran90 pointer to the array
1599: - ierr - error code
1601: Example of Usage:
1602: .vb
1603: PetscScalar, pointer :: xx_v(:)
1604: ....
1605: call VecGetArrayF90(x,xx_v,ierr)
1606: a = xx_v(3)
1607: call VecRestoreArrayF90(x,xx_v,ierr)
1608: .ve
1610: Level: beginner
1612: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray(), UsingFortran
1614: M*/
1619: /*@C
1620: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
1621: processor's portion of the vector data. You MUST call VecRestoreArray2d()
1622: when you no longer need access to the array.
1624: Not Collective
1626: Input Parameter:
1627: + x - the vector
1628: . m - first dimension of two dimensional array
1629: . n - second dimension of two dimensional array
1630: . mstart - first index you will use in first coordinate direction (often 0)
1631: - nstart - first index in the second coordinate direction (often 0)
1633: Output Parameter:
1634: . a - location to put pointer to the array
1636: Level: developer
1638: Notes:
1639: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
1640: obtained from the corner indices obtained from DAGetGhostCorners() while for
1641: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1642: the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
1643:
1644: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1646: Concepts: vector^accessing local values as 2d array
1648: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1649: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1650: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1651: @*/
1652: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1653: {
1655: PetscInt i,N;
1656: PetscScalar *aa;
1662: VecGetLocalSize(x,&N);
1663: 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);
1664: VecGetArray(x,&aa);
1666: PetscMalloc(m*sizeof(PetscScalar*),a);
1667: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
1668: *a -= mstart;
1669: return(0);
1670: }
1674: /*@C
1675: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
1677: Not Collective
1679: Input Parameters:
1680: + x - the vector
1681: . m - first dimension of two dimensional array
1682: . n - second dimension of the two dimensional array
1683: . mstart - first index you will use in first coordinate direction (often 0)
1684: . nstart - first index in the second coordinate direction (often 0)
1685: - a - location of pointer to array obtained from VecGetArray2d()
1687: Level: developer
1689: Notes:
1690: For regular PETSc vectors this routine does not involve any copies. For
1691: any special vectors that do not store local vector data in a contiguous
1692: array, this routine will copy the data back into the underlying
1693: vector data structure from the array obtained with VecGetArray().
1695: This routine actually zeros out the a pointer.
1697: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1698: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1699: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1700: @*/
1701: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1702: {
1704: void *dummy;
1710: dummy = (void*)(*a + mstart);
1711: PetscFree(dummy);
1712: VecRestoreArray(x,PETSC_NULL);
1713: return(0);
1714: }
1718: /*@C
1719: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
1720: processor's portion of the vector data. You MUST call VecRestoreArray1d()
1721: when you no longer need access to the array.
1723: Not Collective
1725: Input Parameter:
1726: + x - the vector
1727: . m - first dimension of two dimensional array
1728: - mstart - first index you will use in first coordinate direction (often 0)
1730: Output Parameter:
1731: . a - location to put pointer to the array
1733: Level: developer
1735: Notes:
1736: For a vector obtained from DACreateLocalVector() mstart are likely
1737: obtained from the corner indices obtained from DAGetGhostCorners() while for
1738: DACreateGlobalVector() they are the corner indices from DAGetCorners().
1739:
1740: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1742: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1743: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1744: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1745: @*/
1746: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1747: {
1749: PetscInt N;
1755: VecGetLocalSize(x,&N);
1756: if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
1757: VecGetArray(x,a);
1758: *a -= mstart;
1759: return(0);
1760: }
1764: /*@C
1765: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
1767: Not Collective
1769: Input Parameters:
1770: + x - the vector
1771: . m - first dimension of two dimensional array
1772: . mstart - first index you will use in first coordinate direction (often 0)
1773: - a - location of pointer to array obtained from VecGetArray21()
1775: Level: developer
1777: Notes:
1778: For regular PETSc vectors this routine does not involve any copies. For
1779: any special vectors that do not store local vector data in a contiguous
1780: array, this routine will copy the data back into the underlying
1781: vector data structure from the array obtained with VecGetArray1d().
1783: This routine actually zeros out the a pointer.
1785: Concepts: vector^accessing local values as 1d array
1787: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1788: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1789: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
1790: @*/
1791: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1792: {
1798: VecRestoreArray(x,PETSC_NULL);
1799: return(0);
1800: }
1805: /*@C
1806: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
1807: processor's portion of the vector data. You MUST call VecRestoreArray3d()
1808: when you no longer need access to the array.
1810: Not Collective
1812: Input Parameter:
1813: + x - the vector
1814: . m - first dimension of three dimensional array
1815: . n - second dimension of three dimensional array
1816: . p - third dimension of three dimensional array
1817: . mstart - first index you will use in first coordinate direction (often 0)
1818: . nstart - first index in the second coordinate direction (often 0)
1819: - pstart - first index in the third coordinate direction (often 0)
1821: Output Parameter:
1822: . a - location to put pointer to the array
1824: Level: developer
1826: Notes:
1827: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1828: obtained from the corner indices obtained from DAGetGhostCorners() while for
1829: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1830: the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
1831:
1832: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1834: Concepts: vector^accessing local values as 3d array
1836: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1837: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1838: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1839: @*/
1840: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1841: {
1843: PetscInt i,N,j;
1844: PetscScalar *aa,**b;
1850: VecGetLocalSize(x,&N);
1851: 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);
1852: VecGetArray(x,&aa);
1854: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
1855: b = (PetscScalar **)((*a) + m);
1856: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
1857: for (i=0; i<m; i++) {
1858: for (j=0; j<n; j++) {
1859: b[i*n+j] = aa + i*n*p + j*p - pstart;
1860: }
1861: }
1862: *a -= mstart;
1863: return(0);
1864: }
1868: /*@C
1869: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
1871: Not Collective
1873: Input Parameters:
1874: + x - the vector
1875: . m - first dimension of three dimensional array
1876: . n - second dimension of the three dimensional array
1877: . p - third dimension of the three dimensional array
1878: . mstart - first index you will use in first coordinate direction (often 0)
1879: . nstart - first index in the second coordinate direction (often 0)
1880: . pstart - first index in the third coordinate direction (often 0)
1881: - a - location of pointer to array obtained from VecGetArray3d()
1883: Level: developer
1885: Notes:
1886: For regular PETSc vectors this routine does not involve any copies. For
1887: any special vectors that do not store local vector data in a contiguous
1888: array, this routine will copy the data back into the underlying
1889: vector data structure from the array obtained with VecGetArray().
1891: This routine actually zeros out the a pointer.
1893: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1894: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1895: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1896: @*/
1897: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1898: {
1900: void *dummy;
1906: dummy = (void*)(*a + mstart);
1907: PetscFree(dummy);
1908: VecRestoreArray(x,PETSC_NULL);
1909: return(0);
1910: }
1914: /*@C
1915: VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
1916: processor's portion of the vector data. You MUST call VecRestoreArray4d()
1917: when you no longer need access to the array.
1919: Not Collective
1921: Input Parameter:
1922: + x - the vector
1923: . m - first dimension of four dimensional array
1924: . n - second dimension of four dimensional array
1925: . p - third dimension of four dimensional array
1926: . q - fourth dimension of four dimensional array
1927: . mstart - first index you will use in first coordinate direction (often 0)
1928: . nstart - first index in the second coordinate direction (often 0)
1929: . pstart - first index in the third coordinate direction (often 0)
1930: - qstart - first index in the fourth coordinate direction (often 0)
1932: Output Parameter:
1933: . a - location to put pointer to the array
1935: Level: beginner
1937: Notes:
1938: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1939: obtained from the corner indices obtained from DAGetGhostCorners() while for
1940: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1941: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
1942:
1943: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1945: Concepts: vector^accessing local values as 3d array
1947: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1948: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1949: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1950: @*/
1951: PetscErrorCode VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1952: {
1954: PetscInt i,N,j,k;
1955: PetscScalar *aa,***b,**c;
1961: VecGetLocalSize(x,&N);
1962: 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);
1963: VecGetArray(x,&aa);
1965: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
1966: b = (PetscScalar ***)((*a) + m);
1967: c = (PetscScalar **)(b + m*n);
1968: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
1969: for (i=0; i<m; i++) {
1970: for (j=0; j<n; j++) {
1971: b[i*n+j] = c + i*n*p + j*p - pstart;
1972: }
1973: }
1974: for (i=0; i<m; i++) {
1975: for (j=0; j<n; j++) {
1976: for (k=0; k<p; k++) {
1977: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
1978: }
1979: }
1980: }
1981: *a -= mstart;
1982: return(0);
1983: }
1987: /*@C
1988: VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.
1990: Not Collective
1992: Input Parameters:
1993: + x - the vector
1994: . m - first dimension of four dimensional array
1995: . n - second dimension of the four dimensional array
1996: . p - third dimension of the four dimensional array
1997: . q - fourth dimension of the four dimensional array
1998: . mstart - first index you will use in first coordinate direction (often 0)
1999: . nstart - first index in the second coordinate direction (often 0)
2000: . pstart - first index in the third coordinate direction (often 0)
2001: . qstart - first index in the fourth coordinate direction (often 0)
2002: - a - location of pointer to array obtained from VecGetArray4d()
2004: Level: beginner
2006: Notes:
2007: For regular PETSc vectors this routine does not involve any copies. For
2008: any special vectors that do not store local vector data in a contiguous
2009: array, this routine will copy the data back into the underlying
2010: vector data structure from the array obtained with VecGetArray().
2012: This routine actually zeros out the a pointer.
2014: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2015: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
2016: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2017: @*/
2018: PetscErrorCode VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2019: {
2021: void *dummy;
2027: dummy = (void*)(*a + mstart);
2028: PetscFree(dummy);
2029: VecRestoreArray(x,PETSC_NULL);
2030: return(0);
2031: }