Actual source code: rvector.c
petsc-3.10.0 2018-09-12
2: /*
3: Provides the interface functions for vector operations that have PetscScalar/PetscReal in the signature
4: These are the vector functions the user calls.
5: */
6: #include <petsc/private/vecimpl.h>
7: static PetscInt VecGetSubVectorSavedStateId = -1;
9: PETSC_EXTERN PetscErrorCode VecValidValues(Vec vec,PetscInt argnum,PetscBool begin)
10: {
11: #if defined(PETSC_USE_DEBUG)
12: PetscErrorCode ierr;
13: PetscInt n,i;
14: const PetscScalar *x;
17: #if defined(PETSC_HAVE_VECCUDA) || defined(PETSC_HAVE_VIENNACL)
18: if ((vec->petscnative || vec->ops->getarray) && (vec->valid_GPU_array == PETSC_OFFLOAD_CPU || vec->valid_GPU_array == PETSC_OFFLOAD_BOTH)) {
19: #else
20: if (vec->petscnative || vec->ops->getarray) {
21: #endif
22: VecGetLocalSize(vec,&n);
23: VecGetArrayRead(vec,&x);
24: for (i=0; i<n; i++) {
25: if (begin) {
26: if (PetscIsInfOrNanScalar(x[i])) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_FP,"Vec entry at local location %D is not-a-number or infinite at beginning of function: Parameter number %D",i,argnum);
27: } else {
28: if (PetscIsInfOrNanScalar(x[i])) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_FP,"Vec entry at local location %D is not-a-number or infinite at end of function: Parameter number %D",i,argnum);
29: }
30: }
31: VecRestoreArrayRead(vec,&x);
32: }
33: return(0);
34: #else
35: return 0;
36: #endif
37: }
39: /*@
40: VecMaxPointwiseDivide - Computes the maximum of the componentwise division max = max_i abs(x_i/y_i).
42: Logically Collective on Vec
44: Input Parameters:
45: . x, y - the vectors
47: Output Parameter:
48: . max - the result
50: Level: advanced
52: Notes:
53: x and y may be the same vector
54: if a particular y_i is zero, it is treated as 1 in the above formula
56: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
57: @*/
58: PetscErrorCode VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
59: {
69: VecCheckSameSize(x,1,y,2);
70: (*x->ops->maxpointwisedivide)(x,y,max);
71: return(0);
72: }
74: /*@
75: VecDot - Computes the vector dot product.
77: Collective on Vec
79: Input Parameters:
80: . x, y - the vectors
82: Output Parameter:
83: . val - the dot product
85: Performance Issues:
86: $ per-processor memory bandwidth
87: $ interprocessor latency
88: $ work load inbalance that causes certain processes to arrive much earlier than others
90: Notes for Users of Complex Numbers:
91: For complex vectors, VecDot() computes
92: $ val = (x,y) = y^H x,
93: where y^H denotes the conjugate transpose of y. Note that this corresponds to the usual "mathematicians" complex
94: inner product where the SECOND argument gets the complex conjugate. Since the BLASdot() complex conjugates the first
95: first argument we call the BLASdot() with the arguments reversed.
97: Use VecTDot() for the indefinite form
98: $ val = (x,y) = y^T x,
99: where y^T denotes the transpose of y.
101: Level: intermediate
103: Concepts: inner product
104: Concepts: vector^inner product
106: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecDotRealPart()
107: @*/
108: PetscErrorCode VecDot(Vec x,Vec y,PetscScalar *val)
109: {
119: VecCheckSameSize(x,1,y,2);
121: PetscLogEventBegin(VEC_Dot,x,y,0,0);
122: (*x->ops->dot)(x,y,val);
123: PetscLogEventEnd(VEC_Dot,x,y,0,0);
124: return(0);
125: }
127: /*@
128: VecDotRealPart - Computes the real part of the vector dot product.
130: Collective on Vec
132: Input Parameters:
133: . x, y - the vectors
135: Output Parameter:
136: . val - the real part of the dot product;
138: Performance Issues:
139: $ per-processor memory bandwidth
140: $ interprocessor latency
141: $ work load inbalance that causes certain processes to arrive much earlier than others
143: Notes for Users of Complex Numbers:
144: See VecDot() for more details on the definition of the dot product for complex numbers
146: For real numbers this returns the same value as VecDot()
148: For complex numbers in C^n (that is a vector of n components with a complex number for each component) this is equal to the usual real dot product on the
149: the space R^{2n} (that is a vector of 2n components with the real or imaginary part of the complex numbers for components)
151: Developer Note: This is not currently optimized to compute only the real part of the dot product.
153: Level: intermediate
155: Concepts: inner product
156: Concepts: vector^inner product
158: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecDot(), VecDotNorm2()
159: @*/
160: PetscErrorCode VecDotRealPart(Vec x,Vec y,PetscReal *val)
161: {
163: PetscScalar fdot;
166: VecDot(x,y,&fdot);
167: *val = PetscRealPart(fdot);
168: return(0);
169: }
171: /*@
172: VecNorm - Computes the vector norm.
174: Collective on Vec
176: Input Parameters:
177: + x - the vector
178: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
179: NORM_1_AND_2, which computes both norms and stores them
180: in a two element array.
182: Output Parameter:
183: . val - the norm
185: Notes:
186: $ NORM_1 denotes sum_i |x_i|
187: $ NORM_2 denotes sqrt(sum_i |x_i|^2)
188: $ NORM_INFINITY denotes max_i |x_i|
190: For complex numbers NORM_1 will return the traditional 1 norm of the 2 norm of the complex numbers; that is the 1
191: norm of the absolutely values of the complex entries. In PETSc 3.6 and earlier releases it returned the 1 norm of
192: the 1 norm of the complex entries (what is returned by the BLAS routine asum()). Both are valid norms but most
193: people expect the former.
195: Level: intermediate
197: Performance Issues:
198: $ per-processor memory bandwidth
199: $ interprocessor latency
200: $ work load inbalance that causes certain processes to arrive much earlier than others
202: Concepts: norm
203: Concepts: vector^norm
205: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNormAvailable(),
206: VecNormBegin(), VecNormEnd()
208: @*/
209: PetscErrorCode VecNorm(Vec x,NormType type,PetscReal *val)
210: {
211: PetscBool flg;
219: /*
220: * Cached data?
221: */
222: if (type!=NORM_1_AND_2) {
223: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,flg);
224: if (flg) return(0);
225: }
226: PetscLogEventBegin(VEC_Norm,x,0,0,0);
227: (*x->ops->norm)(x,type,val);
228: PetscLogEventEnd(VEC_Norm,x,0,0,0);
230: if (type!=NORM_1_AND_2) {
231: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[type],*val);
232: }
233: return(0);
234: }
236: /*@
237: VecNormAvailable - Returns the vector norm if it is already known.
239: Not Collective
241: Input Parameters:
242: + x - the vector
243: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
244: NORM_1_AND_2, which computes both norms and stores them
245: in a two element array.
247: Output Parameter:
248: + available - PETSC_TRUE if the val returned is valid
249: - val - the norm
251: Notes:
252: $ NORM_1 denotes sum_i |x_i|
253: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
254: $ NORM_INFINITY denotes max_i |x_i|
256: Level: intermediate
258: Performance Issues:
259: $ per-processor memory bandwidth
260: $ interprocessor latency
261: $ work load inbalance that causes certain processes to arrive much earlier than others
263: Compile Option:
264: PETSC_HAVE_SLOW_BLAS_NORM2 will cause a C (loop unrolled) version of the norm to be used, rather
265: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
266: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
268: Concepts: norm
269: Concepts: vector^norm
271: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNorm()
272: VecNormBegin(), VecNormEnd()
274: @*/
275: PetscErrorCode VecNormAvailable(Vec x,NormType type,PetscBool *available,PetscReal *val)
276: {
284: *available = PETSC_FALSE;
285: if (type!=NORM_1_AND_2) {
286: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,*available);
287: }
288: return(0);
289: }
291: /*@
292: VecNormalize - Normalizes a vector by 2-norm.
294: Collective on Vec
296: Input Parameters:
297: + x - the vector
299: Output Parameter:
300: . x - the normalized vector
301: - val - the vector norm before normalization
303: Level: intermediate
305: Concepts: vector^normalizing
306: Concepts: normalizing^vector
308: @*/
309: PetscErrorCode VecNormalize(Vec x,PetscReal *val)
310: {
312: PetscReal norm;
317: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
318: VecNorm(x,NORM_2,&norm);
319: if (norm == 0.0) {
320: PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
321: } else if (norm != 1.0) {
322: PetscScalar tmp = 1.0/norm;
323: VecScale(x,tmp);
324: }
325: if (val) *val = norm;
326: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
327: return(0);
328: }
330: /*@C
331: VecMax - Determines the vector component with maximum real part and its location.
333: Collective on Vec
335: Input Parameter:
336: . x - the vector
338: Output Parameters:
339: + p - the location of val (pass NULL if you don't want this)
340: - val - the maximum component
342: Notes:
343: Returns the value PETSC_MIN_REAL and p = -1 if the vector is of length 0.
345: Returns the smallest index with the maximum value
346: Level: intermediate
348: Concepts: maximum^of vector
349: Concepts: vector^maximum value
351: .seealso: VecNorm(), VecMin()
352: @*/
353: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
354: {
361: PetscLogEventBegin(VEC_Max,x,0,0,0);
362: (*x->ops->max)(x,p,val);
363: PetscLogEventEnd(VEC_Max,x,0,0,0);
364: return(0);
365: }
367: /*@C
368: VecMin - Determines the vector component with minimum real part and its location.
370: Collective on Vec
372: Input Parameters:
373: . x - the vector
375: Output Parameter:
376: + p - the location of val (pass NULL if you don't want this location)
377: - val - the minimum component
379: Level: intermediate
381: Notes:
382: Returns the value PETSC_MAX_REAL and p = -1 if the vector is of length 0.
384: This returns the smallest index with the minumum value
386: Concepts: minimum^of vector
387: Concepts: vector^minimum entry
389: .seealso: VecMax()
390: @*/
391: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
392: {
399: PetscLogEventBegin(VEC_Min,x,0,0,0);
400: (*x->ops->min)(x,p,val);
401: PetscLogEventEnd(VEC_Min,x,0,0,0);
402: return(0);
403: }
405: /*@
406: VecTDot - Computes an indefinite vector dot product. That is, this
407: routine does NOT use the complex conjugate.
409: Collective on Vec
411: Input Parameters:
412: . x, y - the vectors
414: Output Parameter:
415: . val - the dot product
417: Notes for Users of Complex Numbers:
418: For complex vectors, VecTDot() computes the indefinite form
419: $ val = (x,y) = y^T x,
420: where y^T denotes the transpose of y.
422: Use VecDot() for the inner product
423: $ val = (x,y) = y^H x,
424: where y^H denotes the conjugate transpose of y.
426: Level: intermediate
428: Concepts: inner product^non-Hermitian
429: Concepts: vector^inner product
430: Concepts: non-Hermitian inner product
432: .seealso: VecDot(), VecMTDot()
433: @*/
434: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
435: {
445: VecCheckSameSize(x,1,y,2);
447: PetscLogEventBegin(VEC_TDot,x,y,0,0);
448: (*x->ops->tdot)(x,y,val);
449: PetscLogEventEnd(VEC_TDot,x,y,0,0);
450: return(0);
451: }
453: /*@
454: VecScale - Scales a vector.
456: Not collective on Vec
458: Input Parameters:
459: + x - the vector
460: - alpha - the scalar
462: Output Parameter:
463: . x - the scaled vector
465: Note:
466: For a vector with n components, VecScale() computes
467: $ x[i] = alpha * x[i], for i=1,...,n.
469: Level: intermediate
471: Concepts: vector^scaling
472: Concepts: scaling^vector
474: @*/
475: PetscErrorCode VecScale(Vec x, PetscScalar alpha)
476: {
477: PetscReal norms[4] = {0.0,0.0,0.0, 0.0};
478: PetscBool flgs[4];
480: PetscInt i;
485: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
486: PetscLogEventBegin(VEC_Scale,x,0,0,0);
487: if (alpha != (PetscScalar)1.0) {
488: /* get current stashed norms */
489: for (i=0; i<4; i++) {
490: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
491: }
492: (*x->ops->scale)(x,alpha);
493: PetscObjectStateIncrease((PetscObject)x);
494: /* put the scaled stashed norms back into the Vec */
495: for (i=0; i<4; i++) {
496: if (flgs[i]) {
497: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
498: }
499: }
500: }
501: PetscLogEventEnd(VEC_Scale,x,0,0,0);
502: return(0);
503: }
505: /*@
506: VecSet - Sets all components of a vector to a single scalar value.
508: Logically Collective on Vec
510: Input Parameters:
511: + x - the vector
512: - alpha - the scalar
514: Output Parameter:
515: . x - the vector
517: Note:
518: For a vector of dimension n, VecSet() computes
519: $ x[i] = alpha, for i=1,...,n,
520: so that all vector entries then equal the identical
521: scalar value, alpha. Use the more general routine
522: VecSetValues() to set different vector entries.
524: You CANNOT call this after you have called VecSetValues() but before you call
525: VecAssemblyBegin/End().
527: Level: beginner
529: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
531: Concepts: vector^setting to constant
533: @*/
534: PetscErrorCode VecSet(Vec x,PetscScalar alpha)
535: {
536: PetscReal val;
542: if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"You cannot call this after you have called VecSetValues() but\n before you have called VecAssemblyBegin/End()");
544: VecLocked(x,1);
546: PetscLogEventBegin(VEC_Set,x,0,0,0);
547: (*x->ops->set)(x,alpha);
548: PetscLogEventEnd(VEC_Set,x,0,0,0);
549: PetscObjectStateIncrease((PetscObject)x);
551: /* norms can be simply set (if |alpha|*N not too large) */
552: val = PetscAbsScalar(alpha);
553: if (x->map->N == 0) {
554: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],0.0l);
555: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],0.0);
556: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],0.0);
557: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],0.0);
558: } else if (val > PETSC_MAX_REAL/x->map->N) {
559: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
560: } else {
561: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
562: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
563: val = PetscSqrtReal((PetscReal)x->map->N) * val;
564: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
565: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
566: }
567: return(0);
568: }
571: /*@
572: VecAXPY - Computes y = alpha x + y.
574: Logically Collective on Vec
576: Input Parameters:
577: + alpha - the scalar
578: - x, y - the vectors
580: Output Parameter:
581: . y - output vector
583: Level: intermediate
585: Notes:
586: x and y MUST be different vectors
588: Concepts: vector^BLAS
589: Concepts: BLAS
591: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
592: @*/
593: PetscErrorCode VecAXPY(Vec y,PetscScalar alpha,Vec x)
594: {
603: VecCheckSameSize(x,1,y,3);
604: if (x == y) SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_ARG_IDN,"x and y cannot be the same vector");
606: VecLocked(y,1);
608: VecLockPush(x);
609: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
610: (*y->ops->axpy)(y,alpha,x);
611: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
612: VecLockPop(x);
613: PetscObjectStateIncrease((PetscObject)y);
614: return(0);
615: }
617: /*@
618: VecAXPBY - Computes y = alpha x + beta y.
620: Logically Collective on Vec
622: Input Parameters:
623: + alpha,beta - the scalars
624: - x, y - the vectors
626: Output Parameter:
627: . y - output vector
629: Level: intermediate
631: Notes:
632: x and y MUST be different vectors
634: Concepts: BLAS
635: Concepts: vector^BLAS
637: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
638: @*/
639: PetscErrorCode VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
640: {
649: VecCheckSameSize(x,1,y,4);
650: if (x == y) SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_ARG_IDN,"x and y cannot be the same vector");
654: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
655: (*y->ops->axpby)(y,alpha,beta,x);
656: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
657: PetscObjectStateIncrease((PetscObject)y);
658: return(0);
659: }
661: /*@
662: VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z
664: Logically Collective on Vec
666: Input Parameters:
667: + alpha,beta, gamma - the scalars
668: - x, y, z - the vectors
670: Output Parameter:
671: . z - output vector
673: Level: intermediate
675: Notes:
676: x, y and z must be different vectors
678: Developer Note: alpha = 1 or gamma = 1 or gamma = 0.0 are handled as special cases
680: Concepts: BLAS
681: Concepts: vector^BLAS
683: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
684: @*/
685: PetscErrorCode VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
686: {
698: VecCheckSameSize(x,1,y,5);
699: VecCheckSameSize(x,1,z,6);
700: if (x == y || x == z) SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_ARG_IDN,"x, y, and z must be different vectors");
701: if (y == z) SETERRQ(PetscObjectComm((PetscObject)y),PETSC_ERR_ARG_IDN,"x, y, and z must be different vectors");
706: PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
707: (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
708: PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
709: PetscObjectStateIncrease((PetscObject)z);
710: return(0);
711: }
713: /*@
714: VecAYPX - Computes y = x + alpha y.
716: Logically Collective on Vec
718: Input Parameters:
719: + alpha - the scalar
720: - x, y - the vectors
722: Output Parameter:
723: . y - output vector
725: Level: intermediate
727: Notes:
728: x and y MUST be different vectors
730: Concepts: vector^BLAS
731: Concepts: BLAS
733: .seealso: VecAXPY(), VecWAXPY()
734: @*/
735: PetscErrorCode VecAYPX(Vec y,PetscScalar alpha,Vec x)
736: {
745: VecCheckSameSize(x,1,y,3);
746: if (x == y) SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_ARG_IDN,"x and y must be different vectors");
749: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
750: (*y->ops->aypx)(y,alpha,x);
751: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
752: PetscObjectStateIncrease((PetscObject)y);
753: return(0);
754: }
757: /*@
758: VecWAXPY - Computes w = alpha x + y.
760: Logically Collective on Vec
762: Input Parameters:
763: + alpha - the scalar
764: - x, y - the vectors
766: Output Parameter:
767: . w - the result
769: Level: intermediate
771: Notes:
772: w cannot be either x or y, but x and y can be the same
774: Concepts: vector^BLAS
775: Concepts: BLAS
777: .seealso: VecAXPY(), VecAYPX(), VecAXPBY()
778: @*/
779: PetscErrorCode VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
780: {
792: VecCheckSameSize(x,3,y,4);
793: VecCheckSameSize(x,3,w,1);
794: if (w == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Result vector w cannot be same as input vector y, suggest VecAXPY()");
795: if (w == x) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Result vector w cannot be same as input vector x, suggest VecAYPX()");
798: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
799: (*w->ops->waxpy)(w,alpha,x,y);
800: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
801: PetscObjectStateIncrease((PetscObject)w);
802: return(0);
803: }
806: /*@C
807: VecSetValues - Inserts or adds values into certain locations of a vector.
809: Not Collective
811: Input Parameters:
812: + x - vector to insert in
813: . ni - number of elements to add
814: . ix - indices where to add
815: . y - array of values
816: - iora - either INSERT_VALUES or ADD_VALUES, where
817: ADD_VALUES adds values to any existing entries, and
818: INSERT_VALUES replaces existing entries with new values
820: Notes:
821: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
823: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
824: options cannot be mixed without intervening calls to the assembly
825: routines.
827: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
828: MUST be called after all calls to VecSetValues() have been completed.
830: VecSetValues() uses 0-based indices in Fortran as well as in C.
832: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
833: negative indices may be passed in ix. These rows are
834: simply ignored. This allows easily inserting element load matrices
835: with homogeneous Dirchlet boundary conditions that you don't want represented
836: in the vector.
838: Level: beginner
840: Concepts: vector^setting values
842: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
843: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
844: @*/
845: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
846: {
851: if (!ni) return(0);
855: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
856: (*x->ops->setvalues)(x,ni,ix,y,iora);
857: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
858: PetscObjectStateIncrease((PetscObject)x);
859: return(0);
860: }
862: /*@
863: VecGetValues - Gets values from certain locations of a vector. Currently
864: can only get values on the same processor
866: Not Collective
868: Input Parameters:
869: + x - vector to get values from
870: . ni - number of elements to get
871: - ix - indices where to get them from (in global 1d numbering)
873: Output Parameter:
874: . y - array of values
876: Notes:
877: The user provides the allocated array y; it is NOT allocated in this routine
879: VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.
881: VecAssemblyBegin() and VecAssemblyEnd() MUST be called before calling this
883: VecGetValues() uses 0-based indices in Fortran as well as in C.
885: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
886: negative indices may be passed in ix. These rows are
887: simply ignored.
889: Level: beginner
891: Concepts: vector^getting values
893: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues()
894: @*/
895: PetscErrorCode VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
896: {
901: if (!ni) return(0);
905: (*x->ops->getvalues)(x,ni,ix,y);
906: return(0);
907: }
909: /*@C
910: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
912: Not Collective
914: Input Parameters:
915: + x - vector to insert in
916: . ni - number of blocks to add
917: . ix - indices where to add in block count, rather than element count
918: . y - array of values
919: - iora - either INSERT_VALUES or ADD_VALUES, where
920: ADD_VALUES adds values to any existing entries, and
921: INSERT_VALUES replaces existing entries with new values
923: Notes:
924: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
925: for j=0,...,bs-1, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
927: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
928: options cannot be mixed without intervening calls to the assembly
929: routines.
931: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
932: MUST be called after all calls to VecSetValuesBlocked() have been completed.
934: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
936: Negative indices may be passed in ix, these rows are
937: simply ignored. This allows easily inserting element load matrices
938: with homogeneous Dirchlet boundary conditions that you don't want represented
939: in the vector.
941: Level: intermediate
943: Concepts: vector^setting values blocked
945: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
946: VecSetValues()
947: @*/
948: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
949: {
957: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
958: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
959: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
960: PetscObjectStateIncrease((PetscObject)x);
961: return(0);
962: }
965: /*@C
966: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
967: using a local ordering of the nodes.
969: Not Collective
971: Input Parameters:
972: + x - vector to insert in
973: . ni - number of elements to add
974: . ix - indices where to add
975: . y - array of values
976: - iora - either INSERT_VALUES or ADD_VALUES, where
977: ADD_VALUES adds values to any existing entries, and
978: INSERT_VALUES replaces existing entries with new values
980: Level: intermediate
982: Notes:
983: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
985: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
986: options cannot be mixed without intervening calls to the assembly
987: routines.
989: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
990: MUST be called after all calls to VecSetValuesLocal() have been completed.
992: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
994: Concepts: vector^setting values with local numbering
996: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
997: VecSetValuesBlockedLocal()
998: @*/
999: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1000: {
1002: PetscInt lixp[128],*lix = lixp;
1006: if (!ni) return(0);
1011: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1012: if (!x->ops->setvalueslocal) {
1013: if (!x->map->mapping) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1014: if (ni > 128) {
1015: PetscMalloc1(ni,&lix);
1016: }
1017: ISLocalToGlobalMappingApply(x->map->mapping,ni,(PetscInt*)ix,lix);
1018: (*x->ops->setvalues)(x,ni,lix,y,iora);
1019: if (ni > 128) {
1020: PetscFree(lix);
1021: }
1022: } else {
1023: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1024: }
1025: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1026: PetscObjectStateIncrease((PetscObject)x);
1027: return(0);
1028: }
1030: /*@
1031: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1032: using a local ordering of the nodes.
1034: Not Collective
1036: Input Parameters:
1037: + x - vector to insert in
1038: . ni - number of blocks to add
1039: . ix - indices where to add in block count, not element count
1040: . y - array of values
1041: - iora - either INSERT_VALUES or ADD_VALUES, where
1042: ADD_VALUES adds values to any existing entries, and
1043: INSERT_VALUES replaces existing entries with new values
1045: Level: intermediate
1047: Notes:
1048: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
1049: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
1051: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
1052: options cannot be mixed without intervening calls to the assembly
1053: routines.
1055: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
1056: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
1058: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
1061: Concepts: vector^setting values blocked with local numbering
1063: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
1064: VecSetLocalToGlobalMapping()
1065: @*/
1066: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1067: {
1069: PetscInt lixp[128],*lix = lixp;
1076: if (ni > 128) {
1077: PetscMalloc1(ni,&lix);
1078: }
1080: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1081: ISLocalToGlobalMappingApplyBlock(x->map->mapping,ni,(PetscInt*)ix,lix);
1082: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1083: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1084: if (ni > 128) {
1085: PetscFree(lix);
1086: }
1087: PetscObjectStateIncrease((PetscObject)x);
1088: return(0);
1089: }
1091: /*@
1092: VecMTDot - Computes indefinite vector multiple dot products.
1093: That is, it does NOT use the complex conjugate.
1095: Collective on Vec
1097: Input Parameters:
1098: + x - one vector
1099: . nv - number of vectors
1100: - y - array of vectors. Note that vectors are pointers
1102: Output Parameter:
1103: . val - array of the dot products
1105: Notes for Users of Complex Numbers:
1106: For complex vectors, VecMTDot() computes the indefinite form
1107: $ val = (x,y) = y^T x,
1108: where y^T denotes the transpose of y.
1110: Use VecMDot() for the inner product
1111: $ val = (x,y) = y^H x,
1112: where y^H denotes the conjugate transpose of y.
1114: Level: intermediate
1116: Concepts: inner product^multiple
1117: Concepts: vector^multiple inner products
1119: .seealso: VecMDot(), VecTDot()
1120: @*/
1121: PetscErrorCode VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1122: {
1133: VecCheckSameSize(x,1,*y,3);
1135: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1136: (*x->ops->mtdot)(x,nv,y,val);
1137: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1138: return(0);
1139: }
1141: /*@
1142: VecMDot - Computes vector multiple dot products.
1144: Collective on Vec
1146: Input Parameters:
1147: + x - one vector
1148: . nv - number of vectors
1149: - y - array of vectors.
1151: Output Parameter:
1152: . val - array of the dot products (does not allocate the array)
1154: Notes for Users of Complex Numbers:
1155: For complex vectors, VecMDot() computes
1156: $ val = (x,y) = y^H x,
1157: where y^H denotes the conjugate transpose of y.
1159: Use VecMTDot() for the indefinite form
1160: $ val = (x,y) = y^T x,
1161: where y^T denotes the transpose of y.
1163: Level: intermediate
1165: Concepts: inner product^multiple
1166: Concepts: vector^multiple inner products
1168: .seealso: VecMTDot(), VecDot()
1169: @*/
1170: PetscErrorCode VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1171: {
1176: if (!nv) return(0);
1177: if (nv < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1184: VecCheckSameSize(x,1,*y,3);
1186: PetscLogEventBegin(VEC_MDot,x,*y,0,0);
1187: (*x->ops->mdot)(x,nv,y,val);
1188: PetscLogEventEnd(VEC_MDot,x,*y,0,0);
1189: return(0);
1190: }
1192: /*@
1193: VecMAXPY - Computes y = y + sum alpha[j] x[j]
1195: Logically Collective on Vec
1197: Input Parameters:
1198: + nv - number of scalars and x-vectors
1199: . alpha - array of scalars
1200: . y - one vector
1201: - x - array of vectors
1203: Level: intermediate
1205: Notes:
1206: y cannot be any of the x vectors
1208: Concepts: BLAS
1210: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1211: @*/
1212: PetscErrorCode VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1213: {
1215: PetscInt i;
1219: if (!nv) return(0);
1220: if (nv < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);
1227: VecCheckSameSize(y,1,*x,4);
1230: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1231: (*y->ops->maxpy)(y,nv,alpha,x);
1232: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1233: PetscObjectStateIncrease((PetscObject)y);
1234: return(0);
1235: }
1237: /*@
1238: VecGetSubVector - Gets a vector representing part of another vector
1240: Collective on IS (and Vec if nonlocal entries are needed)
1242: Input Arguments:
1243: + X - vector from which to extract a subvector
1244: - is - index set representing portion of X to extract
1246: Output Arguments:
1247: . Y - subvector corresponding to is
1249: Level: advanced
1251: Notes:
1252: The subvector Y should be returned with VecRestoreSubVector().
1254: This function may return a subvector without making a copy, therefore it is not safe to use the original vector while
1255: modifying the subvector. Other non-overlapping subvectors can still be obtained from X using this function.
1257: .seealso: MatCreateSubMatrix()
1258: @*/
1259: PetscErrorCode VecGetSubVector(Vec X,IS is,Vec *Y)
1260: {
1261: PetscErrorCode ierr;
1262: Vec Z;
1268: if (X->ops->getsubvector) {
1269: (*X->ops->getsubvector)(X,is,&Z);
1270: } else { /* Default implementation currently does no caching */
1271: PetscInt gstart,gend,start;
1272: PetscBool contiguous,gcontiguous;
1273: VecGetOwnershipRange(X,&gstart,&gend);
1274: ISContiguousLocal(is,gstart,gend,&start,&contiguous);
1275: MPIU_Allreduce(&contiguous,&gcontiguous,1,MPIU_BOOL,MPI_LAND,PetscObjectComm((PetscObject)is));
1276: if (gcontiguous) { /* We can do a no-copy implementation */
1277: PetscInt n,N,bs;
1278: PetscInt state;
1280: ISGetSize(is,&N);
1281: ISGetLocalSize(is,&n);
1282: VecGetBlockSize(X,&bs);
1283: if (n%bs || bs == 1 || !n) bs = -1; /* Do not decide block size if we do not have to */
1284: VecLockGet(X,&state);
1285: if (state) {
1286: const PetscScalar *x;
1287: VecGetArrayRead(X,&x);
1288: VecCreate(PetscObjectComm((PetscObject)X),&Z);
1289: VecSetType(Z,((PetscObject)X)->type_name);
1290: VecSetSizes(Z,n,N);
1291: VecSetBlockSize(Z,bs);
1292: VecPlaceArray(Z,(PetscScalar*)x+start);
1293: VecLockPush(Z);
1294: VecRestoreArrayRead(X,&x);
1295: } else {
1296: PetscScalar *x;
1297: VecGetArray(X,&x);
1298: VecCreate(PetscObjectComm((PetscObject)X),&Z);
1299: VecSetType(Z,((PetscObject)X)->type_name);
1300: VecSetSizes(Z,n,N);
1301: VecSetBlockSize(Z,bs);
1302: VecPlaceArray(Z,(PetscScalar*)x+start);
1303: VecRestoreArray(X,&x);
1304: }
1305: } else { /* Have to create a scatter and do a copy */
1306: VecScatter scatter;
1307: PetscInt n,N;
1308: ISGetLocalSize(is,&n);
1309: ISGetSize(is,&N);
1310: VecCreate(PetscObjectComm((PetscObject)is),&Z);
1311: VecSetSizes(Z,n,N);
1312: VecSetType(Z,((PetscObject)X)->type_name);
1313: VecScatterCreate(X,is,Z,NULL,&scatter);
1314: VecScatterBegin(scatter,X,Z,INSERT_VALUES,SCATTER_FORWARD);
1315: VecScatterEnd(scatter,X,Z,INSERT_VALUES,SCATTER_FORWARD);
1316: PetscObjectCompose((PetscObject)Z,"VecGetSubVector_Scatter",(PetscObject)scatter);
1317: VecScatterDestroy(&scatter);
1318: }
1319: }
1320: /* Record the state when the subvector was gotten so we know whether its values need to be put back */
1321: if (VecGetSubVectorSavedStateId < 0) {PetscObjectComposedDataRegister(&VecGetSubVectorSavedStateId);}
1322: PetscObjectComposedDataSetInt((PetscObject)Z,VecGetSubVectorSavedStateId,1);
1323: *Y = Z;
1324: return(0);
1325: }
1327: /*@
1328: VecRestoreSubVector - Restores a subvector extracted using VecGetSubVector()
1330: Collective on IS (and Vec if nonlocal entries need to be written)
1332: Input Arguments:
1333: + X - vector from which subvector was obtained
1334: . is - index set representing the subset of X
1335: - Y - subvector being restored
1337: Level: advanced
1339: .seealso: VecGetSubVector()
1340: @*/
1341: PetscErrorCode VecRestoreSubVector(Vec X,IS is,Vec *Y)
1342: {
1350: if (X->ops->restoresubvector) {
1351: (*X->ops->restoresubvector)(X,is,Y);
1352: } else {
1353: PETSC_UNUSED PetscObjectState dummystate = 0;
1354: PetscBool valid;
1355: PetscObjectComposedDataGetInt((PetscObject)*Y,VecGetSubVectorSavedStateId,dummystate,valid);
1356: if (!valid) {
1357: VecScatter scatter;
1359: PetscObjectQuery((PetscObject)*Y,"VecGetSubVector_Scatter",(PetscObject*)&scatter);
1360: if (scatter) {
1361: VecScatterBegin(scatter,*Y,X,INSERT_VALUES,SCATTER_REVERSE);
1362: VecScatterEnd(scatter,*Y,X,INSERT_VALUES,SCATTER_REVERSE);
1363: }
1364: }
1365: VecDestroy(Y);
1366: }
1367: return(0);
1368: }
1370: /*@
1371: VecGetLocalVectorRead - Maps the local portion of a vector into a
1372: vector. You must call VecRestoreLocalVectorRead() when the local
1373: vector is no longer needed.
1375: Not collective.
1377: Input parameter:
1378: . v - The vector for which the local vector is desired.
1380: Output parameter:
1381: . w - Upon exit this contains the local vector.
1383: Level: beginner
1385: Notes:
1386: This function is similar to VecGetArrayRead() which maps the local
1387: portion into a raw pointer. VecGetLocalVectorRead() is usually
1388: almost as efficient as VecGetArrayRead() but in certain circumstances
1389: VecGetLocalVectorRead() can be much more efficient than
1390: VecGetArrayRead(). This is because the construction of a contiguous
1391: array representing the vector data required by VecGetArrayRead() can
1392: be an expensive operation for certain vector types. For example, for
1393: GPU vectors VecGetArrayRead() requires that the data between device
1394: and host is synchronized.
1396: Unlike VecGetLocalVector(), this routine is not collective and
1397: preserves cached information.
1399: .seealso: VecRestoreLocalVectorRead(), VecGetLocalVector(), VecGetArrayRead(), VecGetArray()
1400: @*/
1401: PetscErrorCode VecGetLocalVectorRead(Vec v,Vec w)
1402: {
1404: PetscScalar *a;
1409: VecCheckSameLocalSize(v,1,w,2);
1410: if (v->ops->getlocalvectorread) {
1411: (*v->ops->getlocalvectorread)(v,w);
1412: } else {
1413: VecGetArrayRead(v,(const PetscScalar**)&a);
1414: VecPlaceArray(w,a);
1415: }
1416: return(0);
1417: }
1419: /*@
1420: VecRestoreLocalVectorRead - Unmaps the local portion of a vector
1421: previously mapped into a vector using VecGetLocalVectorRead().
1423: Not collective.
1425: Input parameter:
1426: . v - The local portion of this vector was previously mapped into w using VecGetLocalVectorRead().
1427: . w - The vector into which the local portion of v was mapped.
1429: Level: beginner
1431: .seealso: VecGetLocalVectorRead(), VecGetLocalVector(), VecGetArrayRead(), VecGetArray()
1432: @*/
1433: PetscErrorCode VecRestoreLocalVectorRead(Vec v,Vec w)
1434: {
1436: PetscScalar *a;
1441: if (v->ops->restorelocalvectorread) {
1442: (*v->ops->restorelocalvectorread)(v,w);
1443: } else {
1444: VecGetArrayRead(w,(const PetscScalar**)&a);
1445: VecRestoreArrayRead(v,(const PetscScalar**)&a);
1446: VecResetArray(w);
1447: }
1448: return(0);
1449: }
1451: /*@
1452: VecGetLocalVector - Maps the local portion of a vector into a
1453: vector.
1455: Collective on v, not collective on w.
1457: Input parameter:
1458: . v - The vector for which the local vector is desired.
1460: Output parameter:
1461: . w - Upon exit this contains the local vector.
1463: Level: beginner
1465: Notes:
1466: This function is similar to VecGetArray() which maps the local
1467: portion into a raw pointer. VecGetLocalVector() is usually about as
1468: efficient as VecGetArray() but in certain circumstances
1469: VecGetLocalVector() can be much more efficient than VecGetArray().
1470: This is because the construction of a contiguous array representing
1471: the vector data required by VecGetArray() can be an expensive
1472: operation for certain vector types. For example, for GPU vectors
1473: VecGetArray() requires that the data between device and host is
1474: synchronized.
1476: .seealso: VecRestoreLocalVector(), VecGetLocalVectorRead(), VecGetArrayRead(), VecGetArray()
1477: @*/
1478: PetscErrorCode VecGetLocalVector(Vec v,Vec w)
1479: {
1481: PetscScalar *a;
1486: VecCheckSameLocalSize(v,1,w,2);
1487: if (v->ops->getlocalvector) {
1488: (*v->ops->getlocalvector)(v,w);
1489: } else {
1490: VecGetArray(v,&a);
1491: VecPlaceArray(w,a);
1492: }
1493: return(0);
1494: }
1496: /*@
1497: VecRestoreLocalVector - Unmaps the local portion of a vector
1498: previously mapped into a vector using VecGetLocalVector().
1500: Logically collective.
1502: Input parameter:
1503: . v - The local portion of this vector was previously mapped into w using VecGetLocalVector().
1504: . w - The vector into which the local portion of v was mapped.
1506: Level: beginner
1508: .seealso: VecGetLocalVector(), VecGetLocalVectorRead(), VecRestoreLocalVectorRead(), LocalVectorRead(), VecGetArrayRead(), VecGetArray()
1509: @*/
1510: PetscErrorCode VecRestoreLocalVector(Vec v,Vec w)
1511: {
1513: PetscScalar *a;
1518: if (v->ops->restorelocalvector) {
1519: (*v->ops->restorelocalvector)(v,w);
1520: } else {
1521: VecGetArray(w,&a);
1522: VecRestoreArray(v,&a);
1523: VecResetArray(w);
1524: }
1525: return(0);
1526: }
1528: /*@C
1529: VecGetArray - Returns a pointer to a contiguous array that contains this
1530: processor's portion of the vector data. For the standard PETSc
1531: vectors, VecGetArray() returns a pointer to the local data array and
1532: does not use any copies. If the underlying vector data is not stored
1533: in a contiguous array this routine will copy the data to a contiguous
1534: array and return a pointer to that. You MUST call VecRestoreArray()
1535: when you no longer need access to the array.
1537: Logically Collective on Vec
1539: Input Parameter:
1540: . x - the vector
1542: Output Parameter:
1543: . a - location to put pointer to the array
1545: Fortran Note:
1546: This routine is used differently from Fortran 77
1547: $ Vec x
1548: $ PetscScalar x_array(1)
1549: $ PetscOffset i_x
1550: $ PetscErrorCode ierr
1551: $ call VecGetArray(x,x_array,i_x,ierr)
1552: $
1553: $ Access first local entry in vector with
1554: $ value = x_array(i_x + 1)
1555: $
1556: $ ...... other code
1557: $ call VecRestoreArray(x,x_array,i_x,ierr)
1558: For Fortran 90 see VecGetArrayF90()
1560: See the Fortran chapter of the users manual and
1561: petsc/src/snes/examples/tutorials/ex5f.F for details.
1563: Level: beginner
1565: Concepts: vector^accessing local values
1567: .seealso: VecRestoreArray(), VecGetArrayRead(), VecGetArrays(), VecGetArrayF90(), VecGetArrayReadF90(), VecPlaceArray(), VecGetArray2d(),
1568: VecGetArrayPair(), VecRestoreArrayPair()
1569: @*/
1570: PetscErrorCode VecGetArray(Vec x,PetscScalar **a)
1571: {
1573: #if defined(PETSC_HAVE_VIENNACL)
1574: PetscBool is_viennacltype = PETSC_FALSE;
1575: #endif
1579: VecLocked(x,1);
1580: if (x->petscnative) {
1581: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_VECCUDA)
1582: if (x->valid_GPU_array == PETSC_OFFLOAD_GPU) {
1583: #if defined(PETSC_HAVE_VIENNACL)
1584: PetscObjectTypeCompareAny((PetscObject)x,&is_viennacltype,VECSEQVIENNACL,VECMPIVIENNACL,VECVIENNACL,"");
1585: if (is_viennacltype) {
1586: VecViennaCLCopyFromGPU(x);
1587: } else
1588: #endif
1589: {
1590: #if defined(PETSC_HAVE_VECCUDA)
1591: VecCUDACopyFromGPU(x);
1592: #endif
1593: }
1594: } else if (x->valid_GPU_array == PETSC_OFFLOAD_UNALLOCATED) {
1595: #if defined(PETSC_HAVE_VIENNACL)
1596: PetscObjectTypeCompareAny((PetscObject)x,&is_viennacltype,VECSEQVIENNACL,VECMPIVIENNACL,VECVIENNACL,"");
1597: if (is_viennacltype) {
1598: VecViennaCLAllocateCheckHost(x);
1599: } else
1600: #endif
1601: {
1602: #if defined(PETSC_HAVE_VECCUDA)
1603: VecCUDAAllocateCheckHost(x);
1604: #endif
1605: }
1606: }
1607: #endif
1608: *a = *((PetscScalar**)x->data);
1609: } else {
1610: (*x->ops->getarray)(x,a);
1611: }
1612: return(0);
1613: }
1615: /*@C
1616: VecGetArrayRead - Get read-only pointer to contiguous array containing this processor's portion of the vector data.
1618: Not Collective
1620: Input Parameters:
1621: . x - the vector
1623: Output Parameter:
1624: . a - the array
1626: Level: beginner
1628: Notes:
1629: The array must be returned using a matching call to VecRestoreArrayRead().
1631: Unlike VecGetArray(), this routine is not collective and preserves cached information like vector norms.
1633: Standard PETSc vectors use contiguous storage so that this routine does not perform a copy. Other vector
1634: implementations may require a copy, but must such implementations should cache the contiguous representation so that
1635: only one copy is performed when this routine is called multiple times in sequence.
1637: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
1638: @*/
1639: PetscErrorCode VecGetArrayRead(Vec x,const PetscScalar **a)
1640: {
1642: #if defined(PETSC_HAVE_VIENNACL)
1643: PetscBool is_viennacltype = PETSC_FALSE;
1644: #endif
1648: if (x->petscnative) {
1649: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_VECCUDA)
1650: if (x->valid_GPU_array == PETSC_OFFLOAD_GPU) {
1651: #if defined(PETSC_HAVE_VIENNACL)
1652: PetscObjectTypeCompareAny((PetscObject)x,&is_viennacltype,VECSEQVIENNACL,VECMPIVIENNACL,VECVIENNACL,"");
1653: if (is_viennacltype) {
1654: VecViennaCLCopyFromGPU(x);
1655: } else
1656: #endif
1657: {
1658: #if defined(PETSC_HAVE_VECCUDA)
1659: VecCUDACopyFromGPU(x);
1660: #endif
1661: }
1662: }
1663: #endif
1664: *a = *((PetscScalar **)x->data);
1665: } else if (x->ops->getarrayread) {
1666: (*x->ops->getarrayread)(x,a);
1667: } else {
1668: (*x->ops->getarray)(x,(PetscScalar**)a);
1669: }
1670: return(0);
1671: }
1673: /*@C
1674: VecGetArrays - Returns a pointer to the arrays in a set of vectors
1675: that were created by a call to VecDuplicateVecs(). You MUST call
1676: VecRestoreArrays() when you no longer need access to the array.
1678: Logically Collective on Vec
1680: Input Parameter:
1681: + x - the vectors
1682: - n - the number of vectors
1684: Output Parameter:
1685: . a - location to put pointer to the array
1687: Fortran Note:
1688: This routine is not supported in Fortran.
1690: Level: intermediate
1692: .seealso: VecGetArray(), VecRestoreArrays()
1693: @*/
1694: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1695: {
1697: PetscInt i;
1698: PetscScalar **q;
1704: if (n <= 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
1705: PetscMalloc1(n,&q);
1706: for (i=0; i<n; ++i) {
1707: VecGetArray(x[i],&q[i]);
1708: }
1709: *a = q;
1710: return(0);
1711: }
1713: /*@C
1714: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1715: has been called.
1717: Logically Collective on Vec
1719: Input Parameters:
1720: + x - the vector
1721: . n - the number of vectors
1722: - a - location of pointer to arrays obtained from VecGetArrays()
1724: Notes:
1725: For regular PETSc vectors this routine does not involve any copies. For
1726: any special vectors that do not store local vector data in a contiguous
1727: array, this routine will copy the data back into the underlying
1728: vector data structure from the arrays obtained with VecGetArrays().
1730: Fortran Note:
1731: This routine is not supported in Fortran.
1733: Level: intermediate
1735: .seealso: VecGetArrays(), VecRestoreArray()
1736: @*/
1737: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1738: {
1740: PetscInt i;
1741: PetscScalar **q = *a;
1748: for (i=0; i<n; ++i) {
1749: VecRestoreArray(x[i],&q[i]);
1750: }
1751: PetscFree(q);
1752: return(0);
1753: }
1755: /*@C
1756: VecRestoreArray - Restores a vector after VecGetArray() has been called.
1758: Logically Collective on Vec
1760: Input Parameters:
1761: + x - the vector
1762: - a - location of pointer to array obtained from VecGetArray()
1764: Level: beginner
1766: Notes:
1767: For regular PETSc vectors this routine does not involve any copies. For
1768: any special vectors that do not store local vector data in a contiguous
1769: array, this routine will copy the data back into the underlying
1770: vector data structure from the array obtained with VecGetArray().
1772: This routine actually zeros out the a pointer. This is to prevent accidental
1773: us of the array after it has been restored. If you pass null for a it will
1774: not zero the array pointer a.
1776: Fortran Note:
1777: This routine is used differently from Fortran 77
1778: $ Vec x
1779: $ PetscScalar x_array(1)
1780: $ PetscOffset i_x
1781: $ PetscErrorCode ierr
1782: $ call VecGetArray(x,x_array,i_x,ierr)
1783: $
1784: $ Access first local entry in vector with
1785: $ value = x_array(i_x + 1)
1786: $
1787: $ ...... other code
1788: $ call VecRestoreArray(x,x_array,i_x,ierr)
1790: See the Fortran chapter of the users manual and
1791: petsc/src/snes/examples/tutorials/ex5f.F for details.
1792: For Fortran 90 see VecRestoreArrayF90()
1794: .seealso: VecGetArray(), VecRestoreArrayRead(), VecRestoreArrays(), VecRestoreArrayF90(), VecRestoreArrayReadF90(), VecPlaceArray(), VecRestoreArray2d(),
1795: VecGetArrayPair(), VecRestoreArrayPair()
1796: @*/
1797: PetscErrorCode VecRestoreArray(Vec x,PetscScalar **a)
1798: {
1803: if (x->petscnative) {
1804: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_VECCUDA)
1805: x->valid_GPU_array = PETSC_OFFLOAD_CPU;
1806: #endif
1807: } else {
1808: (*x->ops->restorearray)(x,a);
1809: }
1810: if (a) *a = NULL;
1811: PetscObjectStateIncrease((PetscObject)x);
1812: return(0);
1813: }
1815: /*@C
1816: VecRestoreArrayRead - Restore array obtained with VecGetArrayRead()
1818: Not Collective
1820: Input Parameters:
1821: + vec - the vector
1822: - array - the array
1824: Level: beginner
1826: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
1827: @*/
1828: PetscErrorCode VecRestoreArrayRead(Vec x,const PetscScalar **a)
1829: {
1834: if (x->petscnative) {
1835: /* nothing */
1836: } else if (x->ops->restorearrayread) {
1837: (*x->ops->restorearrayread)(x,a);
1838: } else {
1839: (*x->ops->restorearray)(x,(PetscScalar**)a);
1840: }
1841: if (a) *a = NULL;
1842: return(0);
1843: }
1845: /*@
1846: VecPlaceArray - Allows one to replace the array in a vector with an
1847: array provided by the user. This is useful to avoid copying an array
1848: into a vector.
1850: Not Collective
1852: Input Parameters:
1853: + vec - the vector
1854: - array - the array
1856: Notes:
1857: You can return to the original array with a call to VecResetArray()
1859: Level: developer
1861: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
1863: @*/
1864: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
1865: {
1872: if (vec->ops->placearray) {
1873: (*vec->ops->placearray)(vec,array);
1874: } else SETERRQ(PetscObjectComm((PetscObject)vec),PETSC_ERR_SUP,"Cannot place array in this type of vector");
1875: PetscObjectStateIncrease((PetscObject)vec);
1876: return(0);
1877: }
1879: /*@C
1880: VecReplaceArray - Allows one to replace the array in a vector with an
1881: array provided by the user. This is useful to avoid copying an array
1882: into a vector.
1884: Not Collective
1886: Input Parameters:
1887: + vec - the vector
1888: - array - the array
1890: Notes:
1891: This permanently replaces the array and frees the memory associated
1892: with the old array.
1894: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
1895: freed by the user. It will be freed when the vector is destroy.
1897: Not supported from Fortran
1899: Level: developer
1901: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
1903: @*/
1904: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
1905: {
1911: if (vec->ops->replacearray) {
1912: (*vec->ops->replacearray)(vec,array);
1913: } else SETERRQ(PetscObjectComm((PetscObject)vec),PETSC_ERR_SUP,"Cannot replace array in this type of vector");
1914: PetscObjectStateIncrease((PetscObject)vec);
1915: return(0);
1916: }
1918: /*MC
1919: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
1920: and makes them accessible via a Fortran90 pointer.
1922: Synopsis:
1923: VecDuplicateVecsF90(Vec x,PetscInt n,{Vec, pointer :: y(:)},integer ierr)
1925: Collective on Vec
1927: Input Parameters:
1928: + x - a vector to mimic
1929: - n - the number of vectors to obtain
1931: Output Parameters:
1932: + y - Fortran90 pointer to the array of vectors
1933: - ierr - error code
1935: Example of Usage:
1936: .vb
1937: #include <petsc/finclude/petscvec.h>
1938: use petscvec
1940: Vec x
1941: Vec, pointer :: y(:)
1942: ....
1943: call VecDuplicateVecsF90(x,2,y,ierr)
1944: call VecSet(y(2),alpha,ierr)
1945: call VecSet(y(2),alpha,ierr)
1946: ....
1947: call VecDestroyVecsF90(2,y,ierr)
1948: .ve
1950: Notes:
1951: Not yet supported for all F90 compilers
1953: Use VecDestroyVecsF90() to free the space.
1955: Level: beginner
1957: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
1959: M*/
1961: /*MC
1962: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
1963: VecGetArrayF90().
1965: Synopsis:
1966: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
1968: Logically Collective on Vec
1970: Input Parameters:
1971: + x - vector
1972: - xx_v - the Fortran90 pointer to the array
1974: Output Parameter:
1975: . ierr - error code
1977: Example of Usage:
1978: .vb
1979: #include <petsc/finclude/petscvec.h>
1980: use petscvec
1982: PetscScalar, pointer :: xx_v(:)
1983: ....
1984: call VecGetArrayF90(x,xx_v,ierr)
1985: xx_v(3) = a
1986: call VecRestoreArrayF90(x,xx_v,ierr)
1987: .ve
1989: Level: beginner
1991: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray(), UsingFortran, VecRestoreArrayReadF90()
1993: M*/
1995: /*MC
1996: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
1998: Synopsis:
1999: VecDestroyVecsF90(PetscInt n,{Vec, pointer :: x(:)},PetscErrorCode ierr)
2001: Collective on Vec
2003: Input Parameters:
2004: + n - the number of vectors previously obtained
2005: - x - pointer to array of vector pointers
2007: Output Parameter:
2008: . ierr - error code
2010: Notes:
2011: Not yet supported for all F90 compilers
2013: Level: beginner
2015: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
2017: M*/
2019: /*MC
2020: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2021: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2022: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
2023: when you no longer need access to the array.
2025: Synopsis:
2026: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2028: Logically Collective on Vec
2030: Input Parameter:
2031: . x - vector
2033: Output Parameters:
2034: + xx_v - the Fortran90 pointer to the array
2035: - ierr - error code
2037: Example of Usage:
2038: .vb
2039: #include <petsc/finclude/petscvec.h>
2040: use petscvec
2042: PetscScalar, pointer :: xx_v(:)
2043: ....
2044: call VecGetArrayF90(x,xx_v,ierr)
2045: xx_v(3) = a
2046: call VecRestoreArrayF90(x,xx_v,ierr)
2047: .ve
2049: If you ONLY intend to read entries from the array and not change any entries you should use VecGetArrayReadF90().
2051: Level: beginner
2053: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray(), VecGetArrayReadF90(), UsingFortran
2055: M*/
2057: /*MC
2058: VecGetArrayReadF90 - Accesses a read only array from Fortran90. For default PETSc
2059: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2060: this routine is implementation dependent. You MUST call VecRestoreArrayReadF90()
2061: when you no longer need access to the array.
2063: Synopsis:
2064: VecGetArrayReadF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2066: Logically Collective on Vec
2068: Input Parameter:
2069: . x - vector
2071: Output Parameters:
2072: + xx_v - the Fortran90 pointer to the array
2073: - ierr - error code
2075: Example of Usage:
2076: .vb
2077: #include <petsc/finclude/petscvec.h>
2078: use petscvec
2080: PetscScalar, pointer :: xx_v(:)
2081: ....
2082: call VecGetArrayReadF90(x,xx_v,ierr)
2083: a = xx_v(3)
2084: call VecRestoreArrayReadF90(x,xx_v,ierr)
2085: .ve
2087: If you intend to write entries into the array you must use VecGetArrayF90().
2089: Level: beginner
2091: .seealso: VecRestoreArrayReadF90(), VecGetArray(), VecRestoreArray(), VecGetArrayRead(), VecRestoreArrayRead(), VecGetArrayF90(), UsingFortran
2093: M*/
2095: /*MC
2096: VecRestoreArrayReadF90 - Restores a readonly vector to a usable state after a call to
2097: VecGetArrayReadF90().
2099: Synopsis:
2100: VecRestoreArrayReadF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2102: Logically Collective on Vec
2104: Input Parameters:
2105: + x - vector
2106: - xx_v - the Fortran90 pointer to the array
2108: Output Parameter:
2109: . ierr - error code
2111: Example of Usage:
2112: .vb
2113: #include <petsc/finclude/petscvec.h>
2114: use petscvec
2116: PetscScalar, pointer :: xx_v(:)
2117: ....
2118: call VecGetArrayReadF90(x,xx_v,ierr)
2119: a = xx_v(3)
2120: call VecRestoreArrayReadF90(x,xx_v,ierr)
2121: .ve
2123: Level: beginner
2125: .seealso: VecGetArrayReadF90(), VecGetArray(), VecRestoreArray(), VecGetArrayRead(), VecRestoreArrayRead(),UsingFortran, VecRestoreArrayF90()
2127: M*/
2129: /*@C
2130: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
2131: processor's portion of the vector data. You MUST call VecRestoreArray2d()
2132: when you no longer need access to the array.
2134: Logically Collective
2136: Input Parameter:
2137: + x - the vector
2138: . m - first dimension of two dimensional array
2139: . n - second dimension of two dimensional array
2140: . mstart - first index you will use in first coordinate direction (often 0)
2141: - nstart - first index in the second coordinate direction (often 0)
2143: Output Parameter:
2144: . a - location to put pointer to the array
2146: Level: developer
2148: Notes:
2149: For a vector obtained from DMCreateLocalVector() mstart and nstart are likely
2150: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2151: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2152: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
2154: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2156: Concepts: vector^accessing local values as 2d array
2158: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2159: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2160: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2161: @*/
2162: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
2163: {
2165: PetscInt i,N;
2166: PetscScalar *aa;
2172: VecGetLocalSize(x,&N);
2173: if (m*n != N) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 2d array dimensions %D by %D",N,m,n);
2174: VecGetArray(x,&aa);
2176: PetscMalloc1(m,a);
2177: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
2178: *a -= mstart;
2179: return(0);
2180: }
2182: /*@C
2183: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
2185: Logically Collective
2187: Input Parameters:
2188: + x - the vector
2189: . m - first dimension of two dimensional array
2190: . n - second dimension of the two dimensional array
2191: . mstart - first index you will use in first coordinate direction (often 0)
2192: . nstart - first index in the second coordinate direction (often 0)
2193: - a - location of pointer to array obtained from VecGetArray2d()
2195: Level: developer
2197: Notes:
2198: For regular PETSc vectors this routine does not involve any copies. For
2199: any special vectors that do not store local vector data in a contiguous
2200: array, this routine will copy the data back into the underlying
2201: vector data structure from the array obtained with VecGetArray().
2203: This routine actually zeros out the a pointer.
2205: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2206: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2207: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2208: @*/
2209: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
2210: {
2212: void *dummy;
2218: dummy = (void*)(*a + mstart);
2219: PetscFree(dummy);
2220: VecRestoreArray(x,NULL);
2221: return(0);
2222: }
2224: /*@C
2225: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
2226: processor's portion of the vector data. You MUST call VecRestoreArray1d()
2227: when you no longer need access to the array.
2229: Logically Collective
2231: Input Parameter:
2232: + x - the vector
2233: . m - first dimension of two dimensional array
2234: - mstart - first index you will use in first coordinate direction (often 0)
2236: Output Parameter:
2237: . a - location to put pointer to the array
2239: Level: developer
2241: Notes:
2242: For a vector obtained from DMCreateLocalVector() mstart are likely
2243: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2244: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners().
2246: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2248: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2249: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2250: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2251: @*/
2252: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
2253: {
2255: PetscInt N;
2261: VecGetLocalSize(x,&N);
2262: if (m != N) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
2263: VecGetArray(x,a);
2264: *a -= mstart;
2265: return(0);
2266: }
2268: /*@C
2269: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
2271: Logically Collective
2273: Input Parameters:
2274: + x - the vector
2275: . m - first dimension of two dimensional array
2276: . mstart - first index you will use in first coordinate direction (often 0)
2277: - a - location of pointer to array obtained from VecGetArray21()
2279: Level: developer
2281: Notes:
2282: For regular PETSc vectors this routine does not involve any copies. For
2283: any special vectors that do not store local vector data in a contiguous
2284: array, this routine will copy the data back into the underlying
2285: vector data structure from the array obtained with VecGetArray1d().
2287: This routine actually zeros out the a pointer.
2289: Concepts: vector^accessing local values as 1d array
2291: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2292: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2293: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
2294: @*/
2295: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
2296: {
2302: VecRestoreArray(x,NULL);
2303: return(0);
2304: }
2307: /*@C
2308: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
2309: processor's portion of the vector data. You MUST call VecRestoreArray3d()
2310: when you no longer need access to the array.
2312: Logically Collective
2314: Input Parameter:
2315: + x - the vector
2316: . m - first dimension of three dimensional array
2317: . n - second dimension of three dimensional array
2318: . p - third dimension of three dimensional array
2319: . mstart - first index you will use in first coordinate direction (often 0)
2320: . nstart - first index in the second coordinate direction (often 0)
2321: - pstart - first index in the third coordinate direction (often 0)
2323: Output Parameter:
2324: . a - location to put pointer to the array
2326: Level: developer
2328: Notes:
2329: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
2330: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2331: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2332: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
2334: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2336: Concepts: vector^accessing local values as 3d array
2338: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2339: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2340: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2341: @*/
2342: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
2343: {
2345: PetscInt i,N,j;
2346: PetscScalar *aa,**b;
2352: VecGetLocalSize(x,&N);
2353: if (m*n*p != N) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 3d array dimensions %D by %D by %D",N,m,n,p);
2354: VecGetArray(x,&aa);
2356: PetscMalloc1(m*sizeof(PetscScalar**)+m*n,a);
2357: b = (PetscScalar**)((*a) + m);
2358: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
2359: for (i=0; i<m; i++)
2360: for (j=0; j<n; j++)
2361: b[i*n+j] = aa + i*n*p + j*p - pstart;
2363: *a -= mstart;
2364: return(0);
2365: }
2367: /*@C
2368: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
2370: Logically Collective
2372: Input Parameters:
2373: + x - the vector
2374: . m - first dimension of three dimensional array
2375: . n - second dimension of the three dimensional array
2376: . p - third dimension of the three dimensional array
2377: . mstart - first index you will use in first coordinate direction (often 0)
2378: . nstart - first index in the second coordinate direction (often 0)
2379: . pstart - first index in the third coordinate direction (often 0)
2380: - a - location of pointer to array obtained from VecGetArray3d()
2382: Level: developer
2384: Notes:
2385: For regular PETSc vectors this routine does not involve any copies. For
2386: any special vectors that do not store local vector data in a contiguous
2387: array, this routine will copy the data back into the underlying
2388: vector data structure from the array obtained with VecGetArray().
2390: This routine actually zeros out the a pointer.
2392: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2393: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2394: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2395: @*/
2396: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
2397: {
2399: void *dummy;
2405: dummy = (void*)(*a + mstart);
2406: PetscFree(dummy);
2407: VecRestoreArray(x,NULL);
2408: return(0);
2409: }
2411: /*@C
2412: VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
2413: processor's portion of the vector data. You MUST call VecRestoreArray4d()
2414: when you no longer need access to the array.
2416: Logically Collective
2418: Input Parameter:
2419: + x - the vector
2420: . m - first dimension of four dimensional array
2421: . n - second dimension of four dimensional array
2422: . p - third dimension of four dimensional array
2423: . q - fourth dimension of four dimensional array
2424: . mstart - first index you will use in first coordinate direction (often 0)
2425: . nstart - first index in the second coordinate direction (often 0)
2426: . pstart - first index in the third coordinate direction (often 0)
2427: - qstart - first index in the fourth coordinate direction (often 0)
2429: Output Parameter:
2430: . a - location to put pointer to the array
2432: Level: beginner
2434: Notes:
2435: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
2436: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2437: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2438: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
2440: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2442: Concepts: vector^accessing local values as 3d array
2444: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2445: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2446: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2447: @*/
2448: PetscErrorCode VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2449: {
2451: PetscInt i,N,j,k;
2452: PetscScalar *aa,***b,**c;
2458: VecGetLocalSize(x,&N);
2459: if (m*n*p*q != N) SETERRQ5(PETSC_COMM_SELF,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);
2460: VecGetArray(x,&aa);
2462: PetscMalloc1(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p,a);
2463: b = (PetscScalar***)((*a) + m);
2464: c = (PetscScalar**)(b + m*n);
2465: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
2466: for (i=0; i<m; i++)
2467: for (j=0; j<n; j++)
2468: b[i*n+j] = c + i*n*p + j*p - pstart;
2469: for (i=0; i<m; i++)
2470: for (j=0; j<n; j++)
2471: for (k=0; k<p; k++)
2472: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
2473: *a -= mstart;
2474: return(0);
2475: }
2477: /*@C
2478: VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.
2480: Logically Collective
2482: Input Parameters:
2483: + x - the vector
2484: . m - first dimension of four dimensional array
2485: . n - second dimension of the four dimensional array
2486: . p - third dimension of the four dimensional array
2487: . q - fourth dimension of the four dimensional array
2488: . mstart - first index you will use in first coordinate direction (often 0)
2489: . nstart - first index in the second coordinate direction (often 0)
2490: . pstart - first index in the third coordinate direction (often 0)
2491: . qstart - first index in the fourth coordinate direction (often 0)
2492: - a - location of pointer to array obtained from VecGetArray4d()
2494: Level: beginner
2496: Notes:
2497: For regular PETSc vectors this routine does not involve any copies. For
2498: any special vectors that do not store local vector data in a contiguous
2499: array, this routine will copy the data back into the underlying
2500: vector data structure from the array obtained with VecGetArray().
2502: This routine actually zeros out the a pointer.
2504: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2505: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2506: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2507: @*/
2508: PetscErrorCode VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2509: {
2511: void *dummy;
2517: dummy = (void*)(*a + mstart);
2518: PetscFree(dummy);
2519: VecRestoreArray(x,NULL);
2520: return(0);
2521: }
2523: /*@C
2524: VecGetArray2dRead - Returns a pointer to a 2d contiguous array that contains this
2525: processor's portion of the vector data. You MUST call VecRestoreArray2dRead()
2526: when you no longer need access to the array.
2528: Logically Collective
2530: Input Parameter:
2531: + x - the vector
2532: . m - first dimension of two dimensional array
2533: . n - second dimension of two dimensional array
2534: . mstart - first index you will use in first coordinate direction (often 0)
2535: - nstart - first index in the second coordinate direction (often 0)
2537: Output Parameter:
2538: . a - location to put pointer to the array
2540: Level: developer
2542: Notes:
2543: For a vector obtained from DMCreateLocalVector() mstart and nstart are likely
2544: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2545: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2546: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
2548: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2550: Concepts: vector^accessing local values as 2d array
2552: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2553: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2554: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2555: @*/
2556: PetscErrorCode VecGetArray2dRead(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
2557: {
2558: PetscErrorCode ierr;
2559: PetscInt i,N;
2560: const PetscScalar *aa;
2566: VecGetLocalSize(x,&N);
2567: if (m*n != N) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 2d array dimensions %D by %D",N,m,n);
2568: VecGetArrayRead(x,&aa);
2570: PetscMalloc1(m,a);
2571: for (i=0; i<m; i++) (*a)[i] = (PetscScalar*) aa + i*n - nstart;
2572: *a -= mstart;
2573: return(0);
2574: }
2576: /*@C
2577: VecRestoreArray2dRead - Restores a vector after VecGetArray2dRead() has been called.
2579: Logically Collective
2581: Input Parameters:
2582: + x - the vector
2583: . m - first dimension of two dimensional array
2584: . n - second dimension of the two dimensional array
2585: . mstart - first index you will use in first coordinate direction (often 0)
2586: . nstart - first index in the second coordinate direction (often 0)
2587: - a - location of pointer to array obtained from VecGetArray2d()
2589: Level: developer
2591: Notes:
2592: For regular PETSc vectors this routine does not involve any copies. For
2593: any special vectors that do not store local vector data in a contiguous
2594: array, this routine will copy the data back into the underlying
2595: vector data structure from the array obtained with VecGetArray().
2597: This routine actually zeros out the a pointer.
2599: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2600: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2601: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2602: @*/
2603: PetscErrorCode VecRestoreArray2dRead(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
2604: {
2606: void *dummy;
2612: dummy = (void*)(*a + mstart);
2613: PetscFree(dummy);
2614: VecRestoreArrayRead(x,NULL);
2615: return(0);
2616: }
2618: /*@C
2619: VecGetArray1dRead - Returns a pointer to a 1d contiguous array that contains this
2620: processor's portion of the vector data. You MUST call VecRestoreArray1dRead()
2621: when you no longer need access to the array.
2623: Logically Collective
2625: Input Parameter:
2626: + x - the vector
2627: . m - first dimension of two dimensional array
2628: - mstart - first index you will use in first coordinate direction (often 0)
2630: Output Parameter:
2631: . a - location to put pointer to the array
2633: Level: developer
2635: Notes:
2636: For a vector obtained from DMCreateLocalVector() mstart are likely
2637: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2638: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners().
2640: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2642: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2643: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2644: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2645: @*/
2646: PetscErrorCode VecGetArray1dRead(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
2647: {
2649: PetscInt N;
2655: VecGetLocalSize(x,&N);
2656: if (m != N) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
2657: VecGetArrayRead(x,(const PetscScalar**)a);
2658: *a -= mstart;
2659: return(0);
2660: }
2662: /*@C
2663: VecRestoreArray1dRead - Restores a vector after VecGetArray1dRead() has been called.
2665: Logically Collective
2667: Input Parameters:
2668: + x - the vector
2669: . m - first dimension of two dimensional array
2670: . mstart - first index you will use in first coordinate direction (often 0)
2671: - a - location of pointer to array obtained from VecGetArray21()
2673: Level: developer
2675: Notes:
2676: For regular PETSc vectors this routine does not involve any copies. For
2677: any special vectors that do not store local vector data in a contiguous
2678: array, this routine will copy the data back into the underlying
2679: vector data structure from the array obtained with VecGetArray1dRead().
2681: This routine actually zeros out the a pointer.
2683: Concepts: vector^accessing local values as 1d array
2685: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2686: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2687: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
2688: @*/
2689: PetscErrorCode VecRestoreArray1dRead(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
2690: {
2696: VecRestoreArrayRead(x,NULL);
2697: return(0);
2698: }
2701: /*@C
2702: VecGetArray3dRead - Returns a pointer to a 3d contiguous array that contains this
2703: processor's portion of the vector data. You MUST call VecRestoreArray3dRead()
2704: when you no longer need access to the array.
2706: Logically Collective
2708: Input Parameter:
2709: + x - the vector
2710: . m - first dimension of three dimensional array
2711: . n - second dimension of three dimensional array
2712: . p - third dimension of three dimensional array
2713: . mstart - first index you will use in first coordinate direction (often 0)
2714: . nstart - first index in the second coordinate direction (often 0)
2715: - pstart - first index in the third coordinate direction (often 0)
2717: Output Parameter:
2718: . a - location to put pointer to the array
2720: Level: developer
2722: Notes:
2723: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
2724: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2725: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2726: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3dRead().
2728: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2730: Concepts: vector^accessing local values as 3d array
2732: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2733: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2734: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2735: @*/
2736: PetscErrorCode VecGetArray3dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
2737: {
2738: PetscErrorCode ierr;
2739: PetscInt i,N,j;
2740: const PetscScalar *aa;
2741: PetscScalar **b;
2747: VecGetLocalSize(x,&N);
2748: if (m*n*p != N) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 3d array dimensions %D by %D by %D",N,m,n,p);
2749: VecGetArrayRead(x,&aa);
2751: PetscMalloc1(m*sizeof(PetscScalar**)+m*n,a);
2752: b = (PetscScalar**)((*a) + m);
2753: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
2754: for (i=0; i<m; i++)
2755: for (j=0; j<n; j++)
2756: b[i*n+j] = (PetscScalar *)aa + i*n*p + j*p - pstart;
2758: *a -= mstart;
2759: return(0);
2760: }
2762: /*@C
2763: VecRestoreArray3dRead - Restores a vector after VecGetArray3dRead() has been called.
2765: Logically Collective
2767: Input Parameters:
2768: + x - the vector
2769: . m - first dimension of three dimensional array
2770: . n - second dimension of the three dimensional array
2771: . p - third dimension of the three dimensional array
2772: . mstart - first index you will use in first coordinate direction (often 0)
2773: . nstart - first index in the second coordinate direction (often 0)
2774: . pstart - first index in the third coordinate direction (often 0)
2775: - a - location of pointer to array obtained from VecGetArray3dRead()
2777: Level: developer
2779: Notes:
2780: For regular PETSc vectors this routine does not involve any copies. For
2781: any special vectors that do not store local vector data in a contiguous
2782: array, this routine will copy the data back into the underlying
2783: vector data structure from the array obtained with VecGetArray().
2785: This routine actually zeros out the a pointer.
2787: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2788: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2789: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2790: @*/
2791: PetscErrorCode VecRestoreArray3dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
2792: {
2794: void *dummy;
2800: dummy = (void*)(*a + mstart);
2801: PetscFree(dummy);
2802: VecRestoreArrayRead(x,NULL);
2803: return(0);
2804: }
2806: /*@C
2807: VecGetArray4dRead - Returns a pointer to a 4d contiguous array that contains this
2808: processor's portion of the vector data. You MUST call VecRestoreArray4dRead()
2809: when you no longer need access to the array.
2811: Logically Collective
2813: Input Parameter:
2814: + x - the vector
2815: . m - first dimension of four dimensional array
2816: . n - second dimension of four dimensional array
2817: . p - third dimension of four dimensional array
2818: . q - fourth dimension of four dimensional array
2819: . mstart - first index you will use in first coordinate direction (often 0)
2820: . nstart - first index in the second coordinate direction (often 0)
2821: . pstart - first index in the third coordinate direction (often 0)
2822: - qstart - first index in the fourth coordinate direction (often 0)
2824: Output Parameter:
2825: . a - location to put pointer to the array
2827: Level: beginner
2829: Notes:
2830: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
2831: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
2832: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
2833: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
2835: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
2837: Concepts: vector^accessing local values as 3d array
2839: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2840: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2841: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2842: @*/
2843: PetscErrorCode VecGetArray4dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2844: {
2845: PetscErrorCode ierr;
2846: PetscInt i,N,j,k;
2847: const PetscScalar *aa;
2848: PetscScalar ***b,**c;
2854: VecGetLocalSize(x,&N);
2855: if (m*n*p*q != N) SETERRQ5(PETSC_COMM_SELF,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);
2856: VecGetArrayRead(x,&aa);
2858: PetscMalloc1(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p,a);
2859: b = (PetscScalar***)((*a) + m);
2860: c = (PetscScalar**)(b + m*n);
2861: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
2862: for (i=0; i<m; i++)
2863: for (j=0; j<n; j++)
2864: b[i*n+j] = c + i*n*p + j*p - pstart;
2865: for (i=0; i<m; i++)
2866: for (j=0; j<n; j++)
2867: for (k=0; k<p; k++)
2868: c[i*n*p+j*p+k] = (PetscScalar*) aa + i*n*p*q + j*p*q + k*q - qstart;
2869: *a -= mstart;
2870: return(0);
2871: }
2873: /*@C
2874: VecRestoreArray4dRead - Restores a vector after VecGetArray3d() has been called.
2876: Logically Collective
2878: Input Parameters:
2879: + x - the vector
2880: . m - first dimension of four dimensional array
2881: . n - second dimension of the four dimensional array
2882: . p - third dimension of the four dimensional array
2883: . q - fourth dimension of the four dimensional array
2884: . mstart - first index you will use in first coordinate direction (often 0)
2885: . nstart - first index in the second coordinate direction (often 0)
2886: . pstart - first index in the third coordinate direction (often 0)
2887: . qstart - first index in the fourth coordinate direction (often 0)
2888: - a - location of pointer to array obtained from VecGetArray4dRead()
2890: Level: beginner
2892: Notes:
2893: For regular PETSc vectors this routine does not involve any copies. For
2894: any special vectors that do not store local vector data in a contiguous
2895: array, this routine will copy the data back into the underlying
2896: vector data structure from the array obtained with VecGetArray().
2898: This routine actually zeros out the a pointer.
2900: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2901: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
2902: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2903: @*/
2904: PetscErrorCode VecRestoreArray4dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2905: {
2907: void *dummy;
2913: dummy = (void*)(*a + mstart);
2914: PetscFree(dummy);
2915: VecRestoreArrayRead(x,NULL);
2916: return(0);
2917: }
2919: #if defined(PETSC_USE_DEBUG)
2921: /*@
2922: VecLockGet - Gets the current lock status of a vector
2924: Logically Collective on Vec
2926: Input Parameter:
2927: . x - the vector
2929: Output Parameter:
2930: . state - greater than zero indicates the vector is still locked
2932: Level: beginner
2934: Concepts: vector^accessing local values
2936: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockPush(), VecLockGet()
2937: @*/
2938: PetscErrorCode VecLockGet(Vec x,PetscInt *state)
2939: {
2942: *state = x->lock;
2943: return(0);
2944: }
2946: /*@
2947: VecLockPush - Lock a vector from writing
2949: Logically Collective on Vec
2951: Input Parameter:
2952: . x - the vector
2954: Notes:
2955: If this is set then calls to VecGetArray() or VecSetValues() or any other routines that change the vectors values will fail.
2957: Call VecLockPop() to remove the latest lock
2959: Level: beginner
2961: Concepts: vector^accessing local values
2963: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockPop(), VecLockGet()
2964: @*/
2965: PetscErrorCode VecLockPush(Vec x)
2966: {
2969: x->lock++;
2970: return(0);
2971: }
2973: /*@
2974: VecLockPop - Unlock a vector from writing
2976: Logically Collective on Vec
2978: Input Parameter:
2979: . x - the vector
2981: Level: beginner
2983: Concepts: vector^accessing local values
2985: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockPush(), VecLockGet()
2986: @*/
2987: PetscErrorCode VecLockPop(Vec x)
2988: {
2991: x->lock--;
2992: if (x->lock < 0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Vector has been unlocked too many times");
2993: return(0);
2994: }
2996: #endif