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(),
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: VecNormalize - Normalizes a vector by 2-norm.
179: Collective on Vec
181: Input Parameters:
182: + x - the vector
184: Output Parameter:
185: . x - the normalized vector
186: - val - the vector norm before normalization
188: Level: intermediate
190: Concepts: vector^normalizing
191: Concepts: normalizing^vector
193: @*/
194: PetscErrorCode VecNormalize(Vec x,PetscReal *val)
195: {
197: PetscReal norm;
202: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
203: VecNorm(x,NORM_2,&norm);
204: if (!norm) {
205: PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
206: } else if (norm != 1.0) {
207: PetscScalar tmp = 1.0/norm;
208: VecScale(x,tmp);
209: }
210: if (val) *val = norm;
211: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
212: return(0);
213: }
217: /*@C
218: VecMax - Determines the maximum vector component and its location.
220: Collective on Vec
222: Input Parameter:
223: . x - the vector
225: Output Parameters:
226: + val - the maximum component
227: - p - the location of val
229: Notes:
230: Returns the value PETSC_MIN and p = -1 if the vector is of length 0.
232: Level: intermediate
234: Concepts: maximum^of vector
235: Concepts: vector^maximum value
237: .seealso: VecNorm(), VecMin()
238: @*/
239: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
240: {
247: PetscLogEventBegin(VEC_Max,x,0,0,0);
248: (*x->ops->max)(x,p,val);
249: PetscLogEventEnd(VEC_Max,x,0,0,0);
250: return(0);
251: }
255: /*@
256: VecMin - Determines the minimum vector component and its location.
258: Collective on Vec
260: Input Parameters:
261: . x - the vector
263: Output Parameter:
264: + val - the minimum component
265: - p - the location of val
267: Level: intermediate
269: Notes:
270: Returns the value PETSC_MAX and p = -1 if the vector is of length 0.
272: Concepts: minimum^of vector
273: Concepts: vector^minimum entry
275: .seealso: VecMax()
276: @*/
277: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
278: {
285: PetscLogEventBegin(VEC_Min,x,0,0,0);
286: (*x->ops->min)(x,p,val);
287: PetscLogEventEnd(VEC_Min,x,0,0,0);
288: return(0);
289: }
293: /*@
294: VecTDot - Computes an indefinite vector dot product. That is, this
295: routine does NOT use the complex conjugate.
297: Collective on Vec
299: Input Parameters:
300: . x, y - the vectors
302: Output Parameter:
303: . val - the dot product
305: Notes for Users of Complex Numbers:
306: For complex vectors, VecTDot() computes the indefinite form
307: $ val = (x,y) = y^T x,
308: where y^T denotes the transpose of y.
310: Use VecDot() for the inner product
311: $ val = (x,y) = y^H x,
312: where y^H denotes the conjugate transpose of y.
314: Level: intermediate
316: Concepts: inner product^non-Hermitian
317: Concepts: vector^inner product
318: Concepts: non-Hermitian inner product
320: .seealso: VecDot(), VecMTDot()
321: @*/
322: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
323: {
335: PetscLogEventBegin(VEC_TDot,x,y,0,0);
336: (*x->ops->tdot)(x,y,val);
337: PetscLogEventEnd(VEC_TDot,x,y,0,0);
338: return(0);
339: }
343: /*@
344: VecScale - Scales a vector.
346: Collective on Vec
348: Input Parameters:
349: + x - the vector
350: - alpha - the scalar
352: Output Parameter:
353: . x - the scaled vector
355: Note:
356: For a vector with n components, VecScale() computes
357: $ x[i] = alpha * x[i], for i=1,...,n.
359: Level: intermediate
361: Concepts: vector^scaling
362: Concepts: scaling^vector
364: @*/
365: PetscErrorCode VecScale (Vec x, PetscScalar alpha)
366: {
367: PetscReal norms[4] = {0.0,0.0,0.0, 0.0};
368: PetscTruth flgs[4];
370: PetscInt i;
375: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
376: PetscLogEventBegin(VEC_Scale,x,0,0,0);
377: if (alpha != 1.0) {
378: (*x->ops->scale)(x,alpha);
380: /*
381: * Update cached data
382: */
383: for (i=0; i<4; i++) {
384: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
385: }
387: /* in general we consider this object touched */
388: PetscObjectStateIncrease((PetscObject)x);
390: for (i=0; i<4; i++) {
391: if (flgs[i]) {
392: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
393: }
394: }
395: }
396: PetscLogEventEnd(VEC_Scale,x,0,0,0);
397: return(0);
398: }
403: /*@
404: VecSet - Sets all components of a vector to a single scalar value.
406: Collective on Vec
408: Input Parameters:
409: + x - the vector
410: - alpha - the scalar
412: Output Parameter:
413: . x - the vector
415: Note:
416: For a vector of dimension n, VecSet() computes
417: $ x[i] = alpha, for i=1,...,n,
418: so that all vector entries then equal the identical
419: scalar value, alpha. Use the more general routine
420: VecSetValues() to set different vector entries.
422: You CANNOT call this after you have called VecSetValues() but before you call
423: VecAssemblyBegin/End().
425: Level: beginner
427: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
429: Concepts: vector^setting to constant
431: @*/
432: PetscErrorCode VecSet(Vec x,PetscScalar alpha)
433: {
434: PetscReal val;
440: 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()");
441: #if defined (PETSC_USE_DEBUG)
442: {
443: PetscReal alpha_local,alpha_max;
444: alpha_local = PetscAbsScalar(alpha);
445: MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,((PetscObject)x)->comm);
446: if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
447: }
448: #endif
450: PetscLogEventBegin(VEC_Set,x,0,0,0);
451: (*x->ops->set)(x,alpha);
452: PetscLogEventEnd(VEC_Set,x,0,0,0);
454: /*
455: * Update cached data
456: */
457: /* in general we consider this object touched */
458: PetscObjectStateIncrease((PetscObject)x);
460: /* however, norms can be simply set */
461: val = PetscAbsScalar(alpha);
462: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
463: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
464: val = sqrt((double)x->map->N) * val;
465: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
466: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
467: return(0);
468: }
473: /*@
474: VecAXPY - Computes y = alpha x + y.
476: Collective on Vec
478: Input Parameters:
479: + alpha - the scalar
480: - x, y - the vectors
482: Output Parameter:
483: . y - output vector
485: Level: intermediate
487: Notes: x and y must be different vectors
489: Concepts: vector^BLAS
490: Concepts: BLAS
492: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
493: @*/
494: PetscErrorCode VecAXPY(Vec y,PetscScalar alpha,Vec x)
495: {
506: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
507: (*y->ops->axpy)(y,alpha,x);
508: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
509: PetscObjectStateIncrease((PetscObject)y);
510: return(0);
511: }
515: /*@
516: VecAXPBY - Computes y = alpha x + beta y.
518: Collective on Vec
520: Input Parameters:
521: + alpha,beta - the scalars
522: - x, y - the vectors
524: Output Parameter:
525: . y - output vector
527: Level: intermediate
529: Notes: x and y must be different vectors
531: Concepts: BLAS
532: Concepts: vector^BLAS
534: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
535: @*/
536: PetscErrorCode VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
537: {
548: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
549: (*y->ops->axpby)(y,alpha,beta,x);
550: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
551: PetscObjectStateIncrease((PetscObject)y);
552: return(0);
553: }
557: /*@
558: VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z
560: Collective on Vec
562: Input Parameters:
563: + alpha,beta, gamma - the scalars
564: - x, y, z - the vectors
566: Output Parameter:
567: . z - output vector
569: Level: intermediate
571: Notes: x, y and z must be different vectors
573: alpha = 1 or gamma = 1 are handled as special cases
575: Concepts: BLAS
576: Concepts: vector^BLAS
578: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
579: @*/
580: PetscErrorCode VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
581: {
596: PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
597: (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
598: PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
599: PetscObjectStateIncrease((PetscObject)y);
600: return(0);
601: }
605: /*@
606: VecAYPX - Computes y = x + alpha y.
608: Collective on Vec
610: Input Parameters:
611: + alpha - the scalar
612: - x, y - the vectors
614: Output Parameter:
615: . y - output vector
617: Level: intermediate
619: Notes: x and y must be different vectors
621: Concepts: vector^BLAS
622: Concepts: BLAS
624: .seealso: VecAXPY(), VecWAXPY()
625: @*/
626: PetscErrorCode VecAYPX(Vec y,PetscScalar alpha,Vec x)
627: {
638: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
639: (*y->ops->aypx)(y,alpha,x);
640: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
641: PetscObjectStateIncrease((PetscObject)y);
642: return(0);
643: }
648: /*@
649: VecWAXPY - Computes w = alpha x + y.
651: Collective on Vec
653: Input Parameters:
654: + alpha - the scalar
655: - x, y - the vectors
657: Output Parameter:
658: . w - the result
660: Level: intermediate
662: Notes: Neither the vector x or y can be the same as vector w
664: Concepts: vector^BLAS
665: Concepts: BLAS
667: .seealso: VecAXPY(), VecAYPX(), VecAXPBY()
668: @*/
669: PetscErrorCode VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
670: {
685: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
686: (*w->ops->waxpy)(w,alpha,x,y);
687: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
688: PetscObjectStateIncrease((PetscObject)w);
689: return(0);
690: }
695: /*@
696: VecSetValues - Inserts or adds values into certain locations of a vector.
698: Not Collective
700: Input Parameters:
701: + x - vector to insert in
702: . ni - number of elements to add
703: . ix - indices where to add
704: . y - array of values
705: - iora - either INSERT_VALUES or ADD_VALUES, where
706: ADD_VALUES adds values to any existing entries, and
707: INSERT_VALUES replaces existing entries with new values
709: Notes:
710: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
712: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
713: options cannot be mixed without intervening calls to the assembly
714: routines.
716: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
717: MUST be called after all calls to VecSetValues() have been completed.
719: VecSetValues() uses 0-based indices in Fortran as well as in C.
721: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
722: negative indices may be passed in ix. These rows are
723: simply ignored. This allows easily inserting element load matrices
724: with homogeneous Dirchlet boundary conditions that you don't want represented
725: in the vector.
727: Level: beginner
729: Concepts: vector^setting values
731: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
732: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
733: @*/
734: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
735: {
743: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
744: (*x->ops->setvalues)(x,ni,ix,y,iora);
745: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
746: PetscObjectStateIncrease((PetscObject)x);
747: return(0);
748: }
752: /*@
753: VecGetValues - Gets values from certain locations of a vector. Currently
754: can only get values on the same processor
756: Collective on Vec
757:
758: Input Parameters:
759: + x - vector to get values from
760: . ni - number of elements to get
761: - ix - indices where to get them from (in global 1d numbering)
763: Output Parameter:
764: . y - array of values
766: Notes:
767: The user provides the allocated array y; it is NOT allocated in this routine
769: VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.
771: VecAssemblyBegin() and VecAssemblyEnd() MUST be called before calling this
773: VecGetValues() uses 0-based indices in Fortran as well as in C.
775: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
776: negative indices may be passed in ix. These rows are
777: simply ignored.
779: Level: beginner
781: Concepts: vector^getting values
783: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
784: VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
785: @*/
786: PetscErrorCode VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
787: {
795: (*x->ops->getvalues)(x,ni,ix,y);
796: return(0);
797: }
801: /*@
802: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
804: Not Collective
806: Input Parameters:
807: + x - vector to insert in
808: . ni - number of blocks to add
809: . ix - indices where to add in block count, rather than element count
810: . y - array of values
811: - iora - either INSERT_VALUES or ADD_VALUES, where
812: ADD_VALUES adds values to any existing entries, and
813: INSERT_VALUES replaces existing entries with new values
815: Notes:
816: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
817: for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
819: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
820: options cannot be mixed without intervening calls to the assembly
821: routines.
823: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
824: MUST be called after all calls to VecSetValuesBlocked() have been completed.
826: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
828: Negative indices may be passed in ix, these rows are
829: simply ignored. This allows easily inserting element load matrices
830: with homogeneous Dirchlet boundary conditions that you don't want represented
831: in the vector.
833: Level: intermediate
835: Concepts: vector^setting values blocked
837: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
838: VecSetValues()
839: @*/
840: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
841: {
849: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
850: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
851: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
852: PetscObjectStateIncrease((PetscObject)x);
853: return(0);
854: }
859: /*@
860: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
861: using a local ordering of the nodes.
863: Not Collective
865: Input Parameters:
866: + x - vector to insert in
867: . ni - number of elements to add
868: . ix - indices where to add
869: . y - array of values
870: - iora - either INSERT_VALUES or ADD_VALUES, where
871: ADD_VALUES adds values to any existing entries, and
872: INSERT_VALUES replaces existing entries with new values
874: Level: intermediate
876: Notes:
877: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
879: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
880: options cannot be mixed without intervening calls to the assembly
881: routines.
883: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
884: MUST be called after all calls to VecSetValuesLocal() have been completed.
886: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
888: Concepts: vector^setting values with local numbering
890: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
891: VecSetValuesBlockedLocal()
892: @*/
893: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
894: {
896: PetscInt lixp[128],*lix = lixp;
904: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
905: if (!x->ops->setvalueslocal) {
906: if (!x->mapping) {
907: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
908: }
909: if (ni > 128) {
910: PetscMalloc(ni*sizeof(PetscInt),&lix);
911: }
912: ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
913: (*x->ops->setvalues)(x,ni,lix,y,iora);
914: if (ni > 128) {
915: PetscFree(lix);
916: }
917: } else {
918: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
919: }
920: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
921: PetscObjectStateIncrease((PetscObject)x);
922: return(0);
923: }
927: /*@
928: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
929: using a local ordering of the nodes.
931: Not Collective
933: Input Parameters:
934: + x - vector to insert in
935: . ni - number of blocks to add
936: . ix - indices where to add in block count, not element count
937: . y - array of values
938: - iora - either INSERT_VALUES or ADD_VALUES, where
939: ADD_VALUES adds values to any existing entries, and
940: INSERT_VALUES replaces existing entries with new values
942: Level: intermediate
944: Notes:
945: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
946: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
948: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
949: options cannot be mixed without intervening calls to the assembly
950: routines.
952: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
953: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
955: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
958: Concepts: vector^setting values blocked with local numbering
960: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
961: VecSetLocalToGlobalMappingBlock()
962: @*/
963: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
964: {
966: PetscInt lixp[128],*lix = lixp;
973: if (!x->bmapping) {
974: SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlock()");
975: }
976: if (ni > 128) {
977: PetscMalloc(ni*sizeof(PetscInt),&lix);
978: }
980: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
981: ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
982: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
983: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
984: if (ni > 128) {
985: PetscFree(lix);
986: }
987: PetscObjectStateIncrease((PetscObject)x);
988: return(0);
989: }
995: /*@
996: VecMTDot - Computes indefinite vector multiple dot products.
997: That is, it does NOT use the complex conjugate.
999: Collective on Vec
1001: Input Parameters:
1002: + x - one vector
1003: . nv - number of vectors
1004: - y - array of vectors. Note that vectors are pointers
1006: Output Parameter:
1007: . val - array of the dot products
1009: Notes for Users of Complex Numbers:
1010: For complex vectors, VecMTDot() computes the indefinite form
1011: $ val = (x,y) = y^T x,
1012: where y^T denotes the transpose of y.
1014: Use VecMDot() for the inner product
1015: $ val = (x,y) = y^H x,
1016: where y^H denotes the conjugate transpose of y.
1018: Level: intermediate
1020: Concepts: inner product^multiple
1021: Concepts: vector^multiple inner products
1023: .seealso: VecMDot(), VecTDot()
1024: @*/
1025: PetscErrorCode VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1026: {
1039: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1040: (*x->ops->mtdot)(x,nv,y,val);
1041: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1042: return(0);
1043: }
1047: /*@
1048: VecMDot - Computes vector multiple dot products.
1050: Collective on Vec
1052: Input Parameters:
1053: + x - one vector
1054: . nv - number of vectors
1055: - y - array of vectors.
1057: Output Parameter:
1058: . val - array of the dot products (does not allocate the array)
1060: Notes for Users of Complex Numbers:
1061: For complex vectors, VecMDot() computes
1062: $ val = (x,y) = y^H x,
1063: where y^H denotes the conjugate transpose of y.
1065: Use VecMTDot() for the indefinite form
1066: $ val = (x,y) = y^T x,
1067: where y^T denotes the transpose of y.
1069: Level: intermediate
1071: Concepts: inner product^multiple
1072: Concepts: vector^multiple inner products
1074: .seealso: VecMTDot(), VecDot()
1075: @*/
1076: PetscErrorCode VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1077: {
1082: if (!nv) return(0);
1083: if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1092: PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1093: (*x->ops->mdot)(x,nv,y,val);
1094: PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1095: return(0);
1096: }
1100: /*@
1101: VecMAXPY - Computes y = y + sum alpha[j] x[j]
1103: Collective on Vec
1105: Input Parameters:
1106: + nv - number of scalars and x-vectors
1107: . alpha - array of scalars
1108: . y - one vector
1109: - x - array of vectors
1111: Level: intermediate
1113: Concepts: BLAS
1115: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1116: @*/
1117: PetscErrorCode VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1118: {
1123: if (!nv) return(0);
1124: if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1133: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1134: (*y->ops->maxpy)(y,nv,alpha,x);
1135: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1136: PetscObjectStateIncrease((PetscObject)y);
1137: return(0);
1138: }
1140: /*MC
1141: VecGetArray - Returns a pointer to a contiguous array that contains this
1142: processor's portion of the vector data. For the standard PETSc
1143: vectors, VecGetArray() returns a pointer to the local data array and
1144: does not use any copies. If the underlying vector data is not stored
1145: in a contiquous array this routine will copy the data to a contiquous
1146: array and return a pointer to that. You MUST call VecRestoreArray()
1147: when you no longer need access to the array.
1149: Synopsis:
1150: PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])
1152: Not Collective
1154: Input Parameter:
1155: . x - the vector
1157: Output Parameter:
1158: . a - location to put pointer to the array
1160: Fortran Note:
1161: This routine is used differently from Fortran 77
1162: $ Vec x
1163: $ PetscScalar x_array(1)
1164: $ PetscOffset i_x
1165: $ PetscErrorCode ierr
1166: $ call VecGetArray(x,x_array,i_x,ierr)
1167: $
1168: $ Access first local entry in vector with
1169: $ value = x_array(i_x + 1)
1170: $
1171: $ ...... other code
1172: $ call VecRestoreArray(x,x_array,i_x,ierr)
1173: For Fortran 90 see VecGetArrayF90()
1175: See the Fortran chapter of the users manual and
1176: petsc/src/snes/examples/tutorials/ex5f.F for details.
1178: Level: beginner
1180: Concepts: vector^accessing local values
1182: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1183: M*/
1186: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
1187: {
1194: (*x->ops->getarray)(x,a);
1195: return(0);
1196: }
1201: /*@C
1202: VecGetArrays - Returns a pointer to the arrays in a set of vectors
1203: that were created by a call to VecDuplicateVecs(). You MUST call
1204: VecRestoreArrays() when you no longer need access to the array.
1206: Not Collective
1208: Input Parameter:
1209: + x - the vectors
1210: - n - the number of vectors
1212: Output Parameter:
1213: . a - location to put pointer to the array
1215: Fortran Note:
1216: This routine is not supported in Fortran.
1218: Level: intermediate
1220: .seealso: VecGetArray(), VecRestoreArrays()
1221: @*/
1222: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1223: {
1225: PetscInt i;
1226: PetscScalar **q;
1232: if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
1233: PetscMalloc(n*sizeof(PetscScalar*),&q);
1234: for (i=0; i<n; ++i) {
1235: VecGetArray(x[i],&q[i]);
1236: }
1237: *a = q;
1238: return(0);
1239: }
1243: /*@C
1244: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1245: has been called.
1247: Not Collective
1249: Input Parameters:
1250: + x - the vector
1251: . n - the number of vectors
1252: - a - location of pointer to arrays obtained from VecGetArrays()
1254: Notes:
1255: For regular PETSc vectors this routine does not involve any copies. For
1256: any special vectors that do not store local vector data in a contiguous
1257: array, this routine will copy the data back into the underlying
1258: vector data structure from the arrays obtained with VecGetArrays().
1260: Fortran Note:
1261: This routine is not supported in Fortran.
1263: Level: intermediate
1265: .seealso: VecGetArrays(), VecRestoreArray()
1266: @*/
1267: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1268: {
1270: PetscInt i;
1271: PetscScalar **q = *a;
1278: for(i=0;i<n;++i) {
1279: VecRestoreArray(x[i],&q[i]);
1280: }
1281: PetscFree(q);
1282: return(0);
1283: }
1285: /*MC
1286: VecRestoreArray - Restores a vector after VecGetArray() has been called.
1288: Not Collective
1290: Synopsis:
1291: PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])
1293: Input Parameters:
1294: + x - the vector
1295: - a - location of pointer to array obtained from VecGetArray()
1297: Level: beginner
1299: Notes:
1300: For regular PETSc vectors this routine does not involve any copies. For
1301: any special vectors that do not store local vector data in a contiguous
1302: array, this routine will copy the data back into the underlying
1303: vector data structure from the array obtained with VecGetArray().
1305: This routine actually zeros out the a pointer. This is to prevent accidental
1306: us of the array after it has been restored. If you pass null for a it will
1307: not zero the array pointer a.
1309: Fortran Note:
1310: This routine is used differently from Fortran 77
1311: $ Vec x
1312: $ PetscScalar x_array(1)
1313: $ PetscOffset i_x
1314: $ PetscErrorCode ierr
1315: $ call VecGetArray(x,x_array,i_x,ierr)
1316: $
1317: $ Access first local entry in vector with
1318: $ value = x_array(i_x + 1)
1319: $
1320: $ ...... other code
1321: $ call VecRestoreArray(x,x_array,i_x,ierr)
1323: See the Fortran chapter of the users manual and
1324: petsc/src/snes/examples/tutorials/ex5f.F for details.
1325: For Fortran 90 see VecRestoreArrayF90()
1327: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
1328: M*/
1331: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
1332: {
1339: #if defined(PETSC_USE_DEBUG)
1340: CHKMEMQ;
1341: #endif
1342: if (x->ops->restorearray) {
1343: (*x->ops->restorearray)(x,a);
1344: }
1345: PetscObjectStateIncrease((PetscObject)x);
1346: return(0);
1347: }
1352: /*@
1353: VecPlaceArray - Allows one to replace the array in a vector with an
1354: array provided by the user. This is useful to avoid copying an array
1355: into a vector.
1357: Not Collective
1359: Input Parameters:
1360: + vec - the vector
1361: - array - the array
1363: Notes:
1364: You can return to the original array with a call to VecResetArray()
1366: Level: developer
1368: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
1370: @*/
1371: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
1372: {
1379: if (vec->ops->placearray) {
1380: (*vec->ops->placearray)(vec,array);
1381: } else {
1382: SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
1383: }
1384: PetscObjectStateIncrease((PetscObject)vec);
1385: return(0);
1386: }
1391: /*@C
1392: VecReplaceArray - Allows one to replace the array in a vector with an
1393: array provided by the user. This is useful to avoid copying an array
1394: into a vector.
1396: Not Collective
1398: Input Parameters:
1399: + vec - the vector
1400: - array - the array
1402: Notes:
1403: This permanently replaces the array and frees the memory associated
1404: with the old array.
1406: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
1407: freed by the user. It will be freed when the vector is destroy.
1409: Not supported from Fortran
1411: Level: developer
1413: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
1415: @*/
1416: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
1417: {
1423: if (vec->ops->replacearray) {
1424: (*vec->ops->replacearray)(vec,array);
1425: } else {
1426: SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
1427: }
1428: PetscObjectStateIncrease((PetscObject)vec);
1429: return(0);
1430: }
1432: /*MC
1433: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
1434: and makes them accessible via a Fortran90 pointer.
1436: Synopsis:
1437: VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)
1439: Collective on Vec
1441: Input Parameters:
1442: + x - a vector to mimic
1443: - n - the number of vectors to obtain
1445: Output Parameters:
1446: + y - Fortran90 pointer to the array of vectors
1447: - ierr - error code
1449: Example of Usage:
1450: .vb
1451: Vec x
1452: Vec, pointer :: y(:)
1453: ....
1454: call VecDuplicateVecsF90(x,2,y,ierr)
1455: call VecSet(y(2),alpha,ierr)
1456: call VecSet(y(2),alpha,ierr)
1457: ....
1458: call VecDestroyVecsF90(y,2,ierr)
1459: .ve
1461: Notes:
1462: Not yet supported for all F90 compilers
1464: Use VecDestroyVecsF90() to free the space.
1466: Level: beginner
1468: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
1470: M*/
1472: /*MC
1473: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
1474: VecGetArrayF90().
1476: Synopsis:
1477: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
1479: Not collective
1481: Input Parameters:
1482: + x - vector
1483: - xx_v - the Fortran90 pointer to the array
1485: Output Parameter:
1486: . ierr - error code
1488: Example of Usage:
1489: .vb
1490: PetscScalar, pointer :: xx_v(:)
1491: ....
1492: call VecGetArrayF90(x,xx_v,ierr)
1493: a = xx_v(3)
1494: call VecRestoreArrayF90(x,xx_v,ierr)
1495: .ve
1496:
1497: Notes:
1498: Not yet supported for all F90 compilers
1500: Level: beginner
1502: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray()
1504: M*/
1506: /*MC
1507: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
1509: Synopsis:
1510: VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)
1512: Input Parameters:
1513: + x - pointer to array of vector pointers
1514: - n - the number of vectors previously obtained
1516: Output Parameter:
1517: . ierr - error code
1519: Notes:
1520: Not yet supported for all F90 compilers
1522: Level: beginner
1524: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
1526: M*/
1528: /*MC
1529: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
1530: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
1531: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
1532: when you no longer need access to the array.
1534: Synopsis:
1535: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
1537: Not Collective
1539: Input Parameter:
1540: . x - vector
1542: Output Parameters:
1543: + xx_v - the Fortran90 pointer to the array
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
1555: Notes:
1556: Not yet supported for all F90 compilers
1558: Level: beginner
1560: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()
1562: M*/
1567: /*@C
1568: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
1569: processor's portion of the vector data. You MUST call VecRestoreArray2d()
1570: when you no longer need access to the array.
1572: Not Collective
1574: Input Parameter:
1575: + x - the vector
1576: . m - first dimension of two dimensional array
1577: . n - second dimension of two dimensional array
1578: . mstart - first index you will use in first coordinate direction (often 0)
1579: - nstart - first index in the second coordinate direction (often 0)
1581: Output Parameter:
1582: . a - location to put pointer to the array
1584: Level: developer
1586: Notes:
1587: For a vector obtained from DACreateLocalVector() mstart and nstart are likely
1588: obtained from the corner indices obtained from DAGetGhostCorners() while for
1589: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1590: the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
1591:
1592: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1594: Concepts: vector^accessing local values as 2d array
1596: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1597: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1598: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1599: @*/
1600: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1601: {
1603: PetscInt i,N;
1604: PetscScalar *aa;
1610: VecGetLocalSize(x,&N);
1611: 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);
1612: VecGetArray(x,&aa);
1614: PetscMalloc(m*sizeof(PetscScalar*),a);
1615: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
1616: *a -= mstart;
1617: return(0);
1618: }
1622: /*@C
1623: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
1625: Not Collective
1627: Input Parameters:
1628: + x - the vector
1629: . m - first dimension of two dimensional array
1630: . n - second dimension of the two dimensional array
1631: . mstart - first index you will use in first coordinate direction (often 0)
1632: . nstart - first index in the second coordinate direction (often 0)
1633: - a - location of pointer to array obtained from VecGetArray2d()
1635: Level: developer
1637: Notes:
1638: For regular PETSc vectors this routine does not involve any copies. For
1639: any special vectors that do not store local vector data in a contiguous
1640: array, this routine will copy the data back into the underlying
1641: vector data structure from the array obtained with VecGetArray().
1643: This routine actually zeros out the a pointer.
1645: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1646: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1647: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1648: @*/
1649: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1650: {
1652: void *dummy;
1658: dummy = (void*)(*a + mstart);
1659: PetscFree(dummy);
1660: VecRestoreArray(x,PETSC_NULL);
1661: return(0);
1662: }
1666: /*@C
1667: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
1668: processor's portion of the vector data. You MUST call VecRestoreArray1d()
1669: when you no longer need access to the array.
1671: Not Collective
1673: Input Parameter:
1674: + x - the vector
1675: . m - first dimension of two dimensional array
1676: - mstart - first index you will use in first coordinate direction (often 0)
1678: Output Parameter:
1679: . a - location to put pointer to the array
1681: Level: developer
1683: Notes:
1684: For a vector obtained from DACreateLocalVector() mstart are likely
1685: obtained from the corner indices obtained from DAGetGhostCorners() while for
1686: DACreateGlobalVector() they are the corner indices from DAGetCorners().
1687:
1688: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1690: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1691: VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1692: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1693: @*/
1694: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1695: {
1697: PetscInt N;
1703: VecGetLocalSize(x,&N);
1704: if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
1705: VecGetArray(x,a);
1706: *a -= mstart;
1707: return(0);
1708: }
1712: /*@C
1713: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
1715: Not Collective
1717: Input Parameters:
1718: + x - the vector
1719: . m - first dimension of two dimensional array
1720: . mstart - first index you will use in first coordinate direction (often 0)
1721: - a - location of pointer to array obtained from VecGetArray21()
1723: Level: developer
1725: Notes:
1726: For regular PETSc vectors this routine does not involve any copies. For
1727: any special vectors that do not store local vector data in a contiguous
1728: array, this routine will copy the data back into the underlying
1729: vector data structure from the array obtained with VecGetArray1d().
1731: This routine actually zeros out the a pointer.
1733: Concepts: vector^accessing local values as 1d array
1735: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1736: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1737: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
1738: @*/
1739: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1740: {
1746: VecRestoreArray(x,PETSC_NULL);
1747: return(0);
1748: }
1753: /*@C
1754: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
1755: processor's portion of the vector data. You MUST call VecRestoreArray3d()
1756: when you no longer need access to the array.
1758: Not Collective
1760: Input Parameter:
1761: + x - the vector
1762: . m - first dimension of three dimensional array
1763: . n - second dimension of three dimensional array
1764: . p - third dimension of three dimensional array
1765: . mstart - first index you will use in first coordinate direction (often 0)
1766: . nstart - first index in the second coordinate direction (often 0)
1767: - pstart - first index in the third coordinate direction (often 0)
1769: Output Parameter:
1770: . a - location to put pointer to the array
1772: Level: developer
1774: Notes:
1775: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1776: obtained from the corner indices obtained from DAGetGhostCorners() while for
1777: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1778: the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
1779:
1780: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1782: Concepts: vector^accessing local values as 3d array
1784: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1785: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1786: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1787: @*/
1788: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1789: {
1791: PetscInt i,N,j;
1792: PetscScalar *aa,**b;
1798: VecGetLocalSize(x,&N);
1799: 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);
1800: VecGetArray(x,&aa);
1802: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
1803: b = (PetscScalar **)((*a) + m);
1804: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
1805: for (i=0; i<m; i++) {
1806: for (j=0; j<n; j++) {
1807: b[i*n+j] = aa + i*n*p + j*p - pstart;
1808: }
1809: }
1810: *a -= mstart;
1811: return(0);
1812: }
1816: /*@C
1817: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
1819: Not Collective
1821: Input Parameters:
1822: + x - the vector
1823: . m - first dimension of three dimensional array
1824: . n - second dimension of the three dimensional array
1825: . p - third dimension of the three dimensional array
1826: . mstart - first index you will use in first coordinate direction (often 0)
1827: . nstart - first index in the second coordinate direction (often 0)
1828: . pstart - first index in the third coordinate direction (often 0)
1829: - a - location of pointer to array obtained from VecGetArray3d()
1831: Level: developer
1833: Notes:
1834: For regular PETSc vectors this routine does not involve any copies. For
1835: any special vectors that do not store local vector data in a contiguous
1836: array, this routine will copy the data back into the underlying
1837: vector data structure from the array obtained with VecGetArray().
1839: This routine actually zeros out the a pointer.
1841: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1842: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1843: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1844: @*/
1845: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1846: {
1848: void *dummy;
1854: dummy = (void*)(*a + mstart);
1855: PetscFree(dummy);
1856: VecRestoreArray(x,PETSC_NULL);
1857: return(0);
1858: }
1862: /*@C
1863: VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
1864: processor's portion of the vector data. You MUST call VecRestoreArray4d()
1865: when you no longer need access to the array.
1867: Not Collective
1869: Input Parameter:
1870: + x - the vector
1871: . m - first dimension of four dimensional array
1872: . n - second dimension of four dimensional array
1873: . p - third dimension of four dimensional array
1874: . q - fourth dimension of four dimensional array
1875: . mstart - first index you will use in first coordinate direction (often 0)
1876: . nstart - first index in the second coordinate direction (often 0)
1877: . pstart - first index in the third coordinate direction (often 0)
1878: - qstart - first index in the fourth coordinate direction (often 0)
1880: Output Parameter:
1881: . a - location to put pointer to the array
1883: Level: beginner
1885: Notes:
1886: For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1887: obtained from the corner indices obtained from DAGetGhostCorners() while for
1888: DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1889: the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
1890:
1891: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
1893: Concepts: vector^accessing local values as 3d array
1895: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1896: VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1897: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1898: @*/
1899: PetscErrorCode VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1900: {
1902: PetscInt i,N,j,k;
1903: PetscScalar *aa,***b,**c;
1909: VecGetLocalSize(x,&N);
1910: 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);
1911: VecGetArray(x,&aa);
1913: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
1914: b = (PetscScalar ***)((*a) + m);
1915: c = (PetscScalar **)(b + m*n);
1916: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
1917: for (i=0; i<m; i++) {
1918: for (j=0; j<n; j++) {
1919: b[i*n+j] = c + i*n*p + j*p - pstart;
1920: }
1921: }
1922: for (i=0; i<m; i++) {
1923: for (j=0; j<n; j++) {
1924: for (k=0; k<p; k++) {
1925: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
1926: }
1927: }
1928: }
1929: *a -= mstart;
1930: return(0);
1931: }
1935: /*@C
1936: VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.
1938: Not Collective
1940: Input Parameters:
1941: + x - the vector
1942: . m - first dimension of four dimensional array
1943: . n - second dimension of the four dimensional array
1944: . p - third dimension of the four dimensional array
1945: . q - fourth dimension of the four dimensional array
1946: . mstart - first index you will use in first coordinate direction (often 0)
1947: . nstart - first index in the second coordinate direction (often 0)
1948: . pstart - first index in the third coordinate direction (often 0)
1949: . qstart - first index in the fourth coordinate direction (often 0)
1950: - a - location of pointer to array obtained from VecGetArray4d()
1952: Level: beginner
1954: Notes:
1955: For regular PETSc vectors this routine does not involve any copies. For
1956: any special vectors that do not store local vector data in a contiguous
1957: array, this routine will copy the data back into the underlying
1958: vector data structure from the array obtained with VecGetArray().
1960: This routine actually zeros out the a pointer.
1962: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1963: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1964: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1965: @*/
1966: PetscErrorCode VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1967: {
1969: void *dummy;
1975: dummy = (void*)(*a + mstart);
1976: PetscFree(dummy);
1977: VecRestoreArray(x,PETSC_NULL);
1978: return(0);
1979: }