Actual source code: rvector.c
1: /*
2: Provides the interface functions for vector operations that have PetscScalar/PetscReal in the signature
3: These are the vector functions the user calls.
4: */
5: #include "petsc/private/sfimpl.h"
6: #include "petscsystypes.h"
7: #include <petsc/private/vecimpl.h>
8: #if defined(PETSC_HAVE_CUDA)
9: #include <../src/vec/vec/impls/dvecimpl.h>
10: #include <petsc/private/cudavecimpl.h>
11: #endif
12: #if defined(PETSC_HAVE_HIP)
13: #include <../src/vec/vec/impls/dvecimpl.h>
14: #include <petsc/private/hipvecimpl.h>
15: #endif
16: PetscInt VecGetSubVectorSavedStateId = -1;
18: PETSC_EXTERN PetscErrorCode VecValidValues(Vec vec,PetscInt argnum,PetscBool begin)
19: {
20: #if defined(PETSC_USE_DEBUG)
21: PetscInt n,i;
22: const PetscScalar *x;
24: #if defined(PETSC_HAVE_DEVICE)
25: if ((vec->petscnative || vec->ops->getarray) && (vec->offloadmask & PETSC_OFFLOAD_CPU)) {
26: #else
27: if (vec->petscnative || vec->ops->getarray) {
28: #endif
29: VecGetLocalSize(vec,&n);
30: VecGetArrayRead(vec,&x);
31: for (i=0; i<n; i++) {
32: if (begin) {
34: } else {
36: }
37: }
38: VecRestoreArrayRead(vec,&x);
39: }
40: #else
41: #endif
42: return 0;
43: }
45: /*@
46: VecMaxPointwiseDivide - Computes the maximum of the componentwise division max = max_i abs(x_i/y_i).
48: Logically Collective on Vec
50: Input Parameters:
51: . x, y - the vectors
53: Output Parameter:
54: . max - the result
56: Level: advanced
58: Notes:
59: x and y may be the same vector
60: if a particular y_i is zero, it is treated as 1 in the above formula
62: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
63: @*/
64: PetscErrorCode VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
65: {
72: VecCheckSameSize(x,1,y,2);
73: (*x->ops->maxpointwisedivide)(x,y,max);
74: return 0;
75: }
77: /*@
78: VecDot - Computes the vector dot product.
80: Collective on Vec
82: Input Parameters:
83: . x, y - the vectors
85: Output Parameter:
86: . val - the dot product
88: Performance Issues:
89: $ per-processor memory bandwidth
90: $ interprocessor latency
91: $ work load imbalance that causes certain processes to arrive much earlier than others
93: Notes for Users of Complex Numbers:
94: For complex vectors, VecDot() computes
95: $ val = (x,y) = y^H x,
96: where y^H denotes the conjugate transpose of y. Note that this corresponds to the usual "mathematicians" complex
97: inner product where the SECOND argument gets the complex conjugate. Since the BLASdot() complex conjugates the first
98: first argument we call the BLASdot() with the arguments reversed.
100: Use VecTDot() for the indefinite form
101: $ val = (x,y) = y^T x,
102: where y^T denotes the transpose of y.
104: Level: intermediate
106: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecDotRealPart()
107: @*/
108: PetscErrorCode VecDot(Vec x,Vec y,PetscScalar *val)
109: {
116: VecCheckSameSize(x,1,y,2);
118: PetscLogEventBegin(VEC_Dot,x,y,0,0);
119: (*x->ops->dot)(x,y,val);
120: PetscLogEventEnd(VEC_Dot,x,y,0,0);
121: return 0;
122: }
124: /*@
125: VecDotRealPart - Computes the real part of the vector dot product.
127: Collective on Vec
129: Input Parameters:
130: . x, y - the vectors
132: Output Parameter:
133: . val - the real part of the dot product;
135: Performance Issues:
136: $ per-processor memory bandwidth
137: $ interprocessor latency
138: $ work load imbalance that causes certain processes to arrive much earlier than others
140: Notes for Users of Complex Numbers:
141: See VecDot() for more details on the definition of the dot product for complex numbers
143: For real numbers this returns the same value as VecDot()
145: 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
146: the space R^{2n} (that is a vector of 2n components with the real or imaginary part of the complex numbers for components)
148: Developer Note: This is not currently optimized to compute only the real part of the dot product.
150: Level: intermediate
152: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecDot(), VecDotNorm2()
153: @*/
154: PetscErrorCode VecDotRealPart(Vec x,Vec y,PetscReal *val)
155: {
156: PetscScalar fdot;
158: VecDot(x,y,&fdot);
159: *val = PetscRealPart(fdot);
160: return 0;
161: }
163: /*@
164: VecNorm - Computes the vector norm.
166: Collective on Vec
168: Input Parameters:
169: + x - the vector
170: - type - the type of the norm requested
172: Output Parameter:
173: . val - the norm
175: Values of NormType:
176: + NORM_1 - sum_i |x_i|
177: . NORM_2 - sqrt(sum_i |x_i|^2)
178: . NORM_INFINITY - max_i |x_i|
179: - NORM_1_AND_2 - computes efficiently both NORM_1 and NORM_2 and stores them each in an output array
181: Notes:
182: For complex numbers NORM_1 will return the traditional 1 norm of the 2 norm of the complex numbers; that is the 1
183: norm of the absolute values of the complex entries. In PETSc 3.6 and earlier releases it returned the 1 norm of
184: the 1 norm of the complex entries (what is returned by the BLAS routine asum()). Both are valid norms but most
185: people expect the former.
187: This routine stashes the computed norm value, repeated calls before the vector entries are changed are then rapid since the
188: precomputed value is immediately available. Certain vector operations such as VecSet() store the norms so the value is
189: immediately available and does not need to be explicitly computed. VecScale() updates any stashed norm values, thus calls after VecScale()
190: do not need to explicitly recompute the norm.
192: Level: intermediate
194: Performance Issues:
195: + per-processor memory bandwidth - limits the speed of the computation of local portion of the norm
196: . interprocessor latency - limits the accumulation of the result across ranks, .i.e. MPI_Allreduce() time
197: . number of ranks - the time for the result will grow with the log base 2 of the number of ranks sharing the vector
198: - work load imbalance - the rank with the largest number of vector entries will limit the speed up
200: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNormAvailable(),
201: VecNormBegin(), VecNormEnd(), NormType()
203: @*/
204: PetscErrorCode VecNorm(Vec x,NormType type,PetscReal *val)
205: {
206: PetscBool flg;
212: /*
213: * Cached data?
214: */
215: if (type!=NORM_1_AND_2) {
216: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,flg);
217: if (flg) return 0;
218: }
219: PetscLogEventBegin(VEC_Norm,x,0,0,0);
220: (*x->ops->norm)(x,type,val);
221: PetscLogEventEnd(VEC_Norm,x,0,0,0);
222: if (type!=NORM_1_AND_2) {
223: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[type],*val);
224: }
225: return 0;
226: }
228: /*@
229: VecNormAvailable - Returns the vector norm if it is already known.
231: Not Collective
233: Input Parameters:
234: + x - the vector
235: - type - one of NORM_1, NORM_2, NORM_INFINITY. Also available
236: NORM_1_AND_2, which computes both norms and stores them
237: in a two element array.
239: Output Parameters:
240: + available - PETSC_TRUE if the val returned is valid
241: - val - the norm
243: Notes:
244: $ NORM_1 denotes sum_i |x_i|
245: $ NORM_2 denotes sqrt(sum_i (x_i)^2)
246: $ NORM_INFINITY denotes max_i |x_i|
248: Level: intermediate
250: Performance Issues:
251: $ per-processor memory bandwidth
252: $ interprocessor latency
253: $ work load imbalance that causes certain processes to arrive much earlier than others
255: Compile Option:
256: PETSC_HAVE_SLOW_BLAS_NORM2 will cause a C (loop unrolled) version of the norm to be used, rather
257: than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines
258: (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow.
260: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNorm()
261: VecNormBegin(), VecNormEnd()
263: @*/
264: PetscErrorCode VecNormAvailable(Vec x,NormType type,PetscBool *available,PetscReal *val)
265: {
270: *available = PETSC_FALSE;
271: if (type!=NORM_1_AND_2) {
272: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,*available);
273: }
274: return 0;
275: }
277: /*@
278: VecNormalize - Normalizes a vector by 2-norm.
280: Collective on Vec
282: Input Parameter:
283: . x - the vector
285: Output Parameter:
286: . val - the vector norm before normalization
288: Level: intermediate
290: @*/
291: PetscErrorCode VecNormalize(Vec x,PetscReal *val)
292: {
293: PetscReal norm;
297: PetscLogEventBegin(VEC_Normalize,x,0,0,0);
298: VecNorm(x,NORM_2,&norm);
299: if (norm == 0.0) {
300: PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
301: } else if (norm != 1.0) {
302: PetscScalar tmp = 1.0/norm;
303: VecScale(x,tmp);
304: }
305: if (val) *val = norm;
306: PetscLogEventEnd(VEC_Normalize,x,0,0,0);
307: return 0;
308: }
310: /*@C
311: VecMax - Determines the vector component with maximum real part and its location.
313: Collective on Vec
315: Input Parameter:
316: . x - the vector
318: Output Parameters:
319: + p - the location of val (pass NULL if you don't want this)
320: - val - the maximum component
322: Notes:
323: Returns the value PETSC_MIN_REAL and negative p if the vector is of length 0.
325: Returns the smallest index with the maximum value
326: Level: intermediate
328: .seealso: VecNorm(), VecMin()
329: @*/
330: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
331: {
335: PetscLogEventBegin(VEC_Max,x,0,0,0);
336: (*x->ops->max)(x,p,val);
337: PetscLogEventEnd(VEC_Max,x,0,0,0);
338: return 0;
339: }
341: /*@C
342: VecMin - Determines the vector component with minimum real part and its location.
344: Collective on Vec
346: Input Parameter:
347: . x - the vector
349: Output Parameters:
350: + p - the location of val (pass NULL if you don't want this location)
351: - val - the minimum component
353: Level: intermediate
355: Notes:
356: Returns the value PETSC_MAX_REAL and negative p if the vector is of length 0.
358: This returns the smallest index with the minumum value
360: .seealso: VecMax()
361: @*/
362: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
363: {
367: PetscLogEventBegin(VEC_Min,x,0,0,0);
368: (*x->ops->min)(x,p,val);
369: PetscLogEventEnd(VEC_Min,x,0,0,0);
370: return 0;
371: }
373: /*@
374: VecTDot - Computes an indefinite vector dot product. That is, this
375: routine does NOT use the complex conjugate.
377: Collective on Vec
379: Input Parameters:
380: . x, y - the vectors
382: Output Parameter:
383: . val - the dot product
385: Notes for Users of Complex Numbers:
386: For complex vectors, VecTDot() computes the indefinite form
387: $ val = (x,y) = y^T x,
388: where y^T denotes the transpose of y.
390: Use VecDot() for the inner product
391: $ val = (x,y) = y^H x,
392: where y^H denotes the conjugate transpose of y.
394: Level: intermediate
396: .seealso: VecDot(), VecMTDot()
397: @*/
398: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
399: {
406: VecCheckSameSize(x,1,y,2);
408: PetscLogEventBegin(VEC_TDot,x,y,0,0);
409: (*x->ops->tdot)(x,y,val);
410: PetscLogEventEnd(VEC_TDot,x,y,0,0);
411: return 0;
412: }
414: /*@
415: VecScale - Scales a vector.
417: Not collective on Vec
419: Input Parameters:
420: + x - the vector
421: - alpha - the scalar
423: Note:
424: For a vector with n components, VecScale() computes
425: $ x[i] = alpha * x[i], for i=1,...,n.
427: Level: intermediate
429: @*/
430: PetscErrorCode VecScale(Vec x, PetscScalar alpha)
431: {
432: PetscReal norms[4] = {0.0,0.0,0.0, 0.0};
433: PetscBool flgs[4];
434: PetscInt i;
439: PetscLogEventBegin(VEC_Scale,x,0,0,0);
440: if (alpha != (PetscScalar)1.0) {
441: VecSetErrorIfLocked(x,1);
442: /* get current stashed norms */
443: for (i=0; i<4; i++) {
444: PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
445: }
446: (*x->ops->scale)(x,alpha);
447: PetscObjectStateIncrease((PetscObject)x);
448: /* put the scaled stashed norms back into the Vec */
449: for (i=0; i<4; i++) {
450: if (flgs[i]) {
451: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
452: }
453: }
454: }
455: PetscLogEventEnd(VEC_Scale,x,0,0,0);
456: return 0;
457: }
459: /*@
460: VecSet - Sets all components of a vector to a single scalar value.
462: Logically Collective on Vec
464: Input Parameters:
465: + x - the vector
466: - alpha - the scalar
468: Output Parameter:
469: . x - the vector
471: Note:
472: For a vector of dimension n, VecSet() computes
473: $ x[i] = alpha, for i=1,...,n,
474: so that all vector entries then equal the identical
475: scalar value, alpha. Use the more general routine
476: VecSetValues() to set different vector entries.
478: You CANNOT call this after you have called VecSetValues() but before you call
479: VecAssemblyBegin/End().
481: Level: beginner
483: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()
485: @*/
486: PetscErrorCode VecSet(Vec x,PetscScalar alpha)
487: {
488: PetscReal val;
494: VecSetErrorIfLocked(x,1);
496: PetscLogEventBegin(VEC_Set,x,0,0,0);
497: (*x->ops->set)(x,alpha);
498: PetscLogEventEnd(VEC_Set,x,0,0,0);
499: PetscObjectStateIncrease((PetscObject)x);
501: /* norms can be simply set (if |alpha|*N not too large) */
502: val = PetscAbsScalar(alpha);
503: if (x->map->N == 0) {
504: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],0.0l);
505: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],0.0);
506: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],0.0);
507: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],0.0);
508: } else if (val > PETSC_MAX_REAL/x->map->N) {
509: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
510: } else {
511: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
512: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
513: val = PetscSqrtReal((PetscReal)x->map->N) * val;
514: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
515: PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
516: }
517: return 0;
518: }
520: /*@
521: VecAXPY - Computes y = alpha x + y.
523: Logically Collective on Vec
525: Input Parameters:
526: + alpha - the scalar
527: - x, y - the vectors
529: Output Parameter:
530: . y - output vector
532: Level: intermediate
534: Notes:
535: x and y MUST be different vectors
536: This routine is optimized for alpha of 0.0, otherwise it calls the BLAS routine
538: $ VecAXPY(y,alpha,x) y = alpha x + y
539: $ VecAYPX(y,beta,x) y = x + beta y
540: $ VecAXPBY(y,alpha,beta,x) y = alpha x + beta y
541: $ VecWAXPY(w,alpha,x,y) w = alpha x + y
542: $ VecAXPBYPCZ(w,alpha,beta,gamma,x,y) z = alpha x + beta y + gamma z
543: $ VecMAXPY(y,nv,alpha[],x[]) y = sum alpha[i] x[i] + y
545: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPBYPCZ(), VecAXPBY()
546: @*/
547: PetscErrorCode VecAXPY(Vec y,PetscScalar alpha,Vec x)
548: {
554: VecCheckSameSize(x,3,y,1);
557: if (alpha == (PetscScalar)0.0) return 0;
558: VecSetErrorIfLocked(y,1);
560: VecLockReadPush(x);
561: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
562: (*y->ops->axpy)(y,alpha,x);
563: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
564: VecLockReadPop(x);
565: PetscObjectStateIncrease((PetscObject)y);
566: return 0;
567: }
569: /*@
570: VecAXPBY - Computes y = alpha x + beta y.
572: Logically Collective on Vec
574: Input Parameters:
575: + alpha,beta - the scalars
576: - x, y - the vectors
578: Output Parameter:
579: . y - output vector
581: Level: intermediate
583: Notes:
584: x and y MUST be different vectors
585: The implementation is optimized for alpha and/or beta values of 0.0 and 1.0
587: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY(), VecAXPBYPCZ()
588: @*/
589: PetscErrorCode VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
590: {
596: VecCheckSameSize(y,1,x,4);
600: if (alpha == (PetscScalar)0.0 && beta == (PetscScalar)1.0) return 0;
601: VecSetErrorIfLocked(y,1);
602: PetscLogEventBegin(VEC_AXPY,x,y,0,0);
603: (*y->ops->axpby)(y,alpha,beta,x);
604: PetscLogEventEnd(VEC_AXPY,x,y,0,0);
605: PetscObjectStateIncrease((PetscObject)y);
606: return 0;
607: }
609: /*@
610: VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z
612: Logically Collective on Vec
614: Input Parameters:
615: + alpha,beta, gamma - the scalars
616: - x, y, z - the vectors
618: Output Parameter:
619: . z - output vector
621: Level: intermediate
623: Notes:
624: x, y and z must be different vectors
625: The implementation is optimized for alpha of 1.0 and gamma of 1.0 or 0.0
627: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY(), VecAXPBY()
628: @*/
629: PetscErrorCode VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
630: {
639: VecCheckSameSize(x,1,y,5);
640: VecCheckSameSize(x,1,z,6);
646: if (alpha == (PetscScalar)0.0 && beta == (PetscScalar)0.0 && gamma == (PetscScalar)1.0) return 0;
647: VecSetErrorIfLocked(z,1);
649: PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
650: (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
651: PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
652: PetscObjectStateIncrease((PetscObject)z);
653: return 0;
654: }
656: /*@
657: VecAYPX - Computes y = x + beta y.
659: Logically Collective on Vec
661: Input Parameters:
662: + beta - the scalar
663: - x, y - the vectors
665: Output Parameter:
666: . y - output vector
668: Level: intermediate
670: Notes:
671: x and y MUST be different vectors
672: The implementation is optimized for beta of -1.0, 0.0, and 1.0
674: .seealso: VecMAXPY(), VecWAXPY(), VecAXPY(), VecAXPBYPCZ(), VecAXPBY()
675: @*/
676: PetscErrorCode VecAYPX(Vec y,PetscScalar beta,Vec x)
677: {
683: VecCheckSameSize(x,1,y,3);
686: VecSetErrorIfLocked(y,1);
688: PetscLogEventBegin(VEC_AYPX,x,y,0,0);
689: (*y->ops->aypx)(y,beta,x);
690: PetscLogEventEnd(VEC_AYPX,x,y,0,0);
691: PetscObjectStateIncrease((PetscObject)y);
692: return 0;
693: }
695: /*@
696: VecWAXPY - Computes w = alpha x + y.
698: Logically Collective on Vec
700: Input Parameters:
701: + alpha - the scalar
702: - x, y - the vectors
704: Output Parameter:
705: . w - the result
707: Level: intermediate
709: Notes:
710: w cannot be either x or y, but x and y can be the same
711: The implementation is optimzed for alpha of -1.0, 0.0, and 1.0
713: .seealso: VecAXPY(), VecAYPX(), VecAXPBY(), VecMAXPY(), VecAXPBYPCZ()
714: @*/
715: PetscErrorCode VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
716: {
725: VecCheckSameSize(x,3,y,4);
726: VecCheckSameSize(x,3,w,1);
730: VecSetErrorIfLocked(w,1);
732: PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
733: (*w->ops->waxpy)(w,alpha,x,y);
734: PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
735: PetscObjectStateIncrease((PetscObject)w);
736: return 0;
737: }
739: /*@C
740: VecSetValues - Inserts or adds values into certain locations of a vector.
742: Not Collective
744: Input Parameters:
745: + x - vector to insert in
746: . ni - number of elements to add
747: . ix - indices where to add
748: . y - array of values
749: - iora - either INSERT_VALUES or ADD_VALUES, where
750: ADD_VALUES adds values to any existing entries, and
751: INSERT_VALUES replaces existing entries with new values
753: Notes:
754: VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.
756: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
757: options cannot be mixed without intervening calls to the assembly
758: routines.
760: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
761: MUST be called after all calls to VecSetValues() have been completed.
763: VecSetValues() uses 0-based indices in Fortran as well as in C.
765: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
766: negative indices may be passed in ix. These rows are
767: simply ignored. This allows easily inserting element load matrices
768: with homogeneous Dirchlet boundary conditions that you don't want represented
769: in the vector.
771: Level: beginner
773: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
774: VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
775: @*/
776: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
777: {
780: if (!ni) return 0;
785: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
786: (*x->ops->setvalues)(x,ni,ix,y,iora);
787: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
788: PetscObjectStateIncrease((PetscObject)x);
789: return 0;
790: }
792: /*@C
793: VecGetValues - Gets values from certain locations of a vector. Currently
794: can only get values on the same processor
796: Not Collective
798: Input Parameters:
799: + x - vector to get values from
800: . ni - number of elements to get
801: - ix - indices where to get them from (in global 1d numbering)
803: Output Parameter:
804: . y - array of values
806: Notes:
807: The user provides the allocated array y; it is NOT allocated in this routine
809: VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.
811: VecAssemblyBegin() and VecAssemblyEnd() MUST be called before calling this
813: VecGetValues() uses 0-based indices in Fortran as well as in C.
815: If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
816: negative indices may be passed in ix. These rows are
817: simply ignored.
819: Level: beginner
821: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues()
822: @*/
823: PetscErrorCode VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
824: {
826: if (!ni) return 0;
830: (*x->ops->getvalues)(x,ni,ix,y);
831: return 0;
832: }
834: /*@C
835: VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.
837: Not Collective
839: Input Parameters:
840: + x - vector to insert in
841: . ni - number of blocks to add
842: . ix - indices where to add in block count, rather than element count
843: . y - array of values
844: - iora - either INSERT_VALUES or ADD_VALUES, where
845: ADD_VALUES adds values to any existing entries, and
846: INSERT_VALUES replaces existing entries with new values
848: Notes:
849: VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j],
850: for j=0,...,bs-1, for i=0,...,ni-1. where bs was set with VecSetBlockSize().
852: Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES
853: options cannot be mixed without intervening calls to the assembly
854: routines.
856: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
857: MUST be called after all calls to VecSetValuesBlocked() have been completed.
859: VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.
861: Negative indices may be passed in ix, these rows are
862: simply ignored. This allows easily inserting element load matrices
863: with homogeneous Dirchlet boundary conditions that you don't want represented
864: in the vector.
866: Level: intermediate
868: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
869: VecSetValues()
870: @*/
871: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
872: {
875: if (!ni) return 0;
880: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
881: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
882: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
883: PetscObjectStateIncrease((PetscObject)x);
884: return 0;
885: }
887: /*@C
888: VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
889: using a local ordering of the nodes.
891: Not Collective
893: Input Parameters:
894: + x - vector to insert in
895: . ni - number of elements to add
896: . ix - indices where to add
897: . y - array of values
898: - iora - either INSERT_VALUES or ADD_VALUES, where
899: ADD_VALUES adds values to any existing entries, and
900: INSERT_VALUES replaces existing entries with new values
902: Level: intermediate
904: Notes:
905: VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.
907: Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES
908: options cannot be mixed without intervening calls to the assembly
909: routines.
911: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
912: MUST be called after all calls to VecSetValuesLocal() have been completed.
914: VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.
916: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
917: VecSetValuesBlockedLocal()
918: @*/
919: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
920: {
921: PetscInt lixp[128],*lix = lixp;
925: if (!ni) return 0;
930: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
931: if (!x->ops->setvalueslocal) {
932: if (x->map->mapping) {
933: if (ni > 128) {
934: PetscMalloc1(ni,&lix);
935: }
936: ISLocalToGlobalMappingApply(x->map->mapping,ni,(PetscInt*)ix,lix);
937: (*x->ops->setvalues)(x,ni,lix,y,iora);
938: if (ni > 128) {
939: PetscFree(lix);
940: }
941: } else {
942: (*x->ops->setvalues)(x,ni,ix,y,iora);
943: }
944: } else {
945: (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
946: }
947: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
948: PetscObjectStateIncrease((PetscObject)x);
949: return 0;
950: }
952: /*@
953: VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
954: using a local ordering of the nodes.
956: Not Collective
958: Input Parameters:
959: + x - vector to insert in
960: . ni - number of blocks to add
961: . ix - indices where to add in block count, not element count
962: . y - array of values
963: - iora - either INSERT_VALUES or ADD_VALUES, where
964: ADD_VALUES adds values to any existing entries, and
965: INSERT_VALUES replaces existing entries with new values
967: Level: intermediate
969: Notes:
970: VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j],
971: for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().
973: Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES
974: options cannot be mixed without intervening calls to the assembly
975: routines.
977: These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd()
978: MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.
980: VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.
982: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(),
983: VecSetLocalToGlobalMapping()
984: @*/
985: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
986: {
987: PetscInt lixp[128],*lix = lixp;
991: if (!ni) return 0;
995: PetscLogEventBegin(VEC_SetValues,x,0,0,0);
996: if (x->map->mapping) {
997: if (ni > 128) {
998: PetscMalloc1(ni,&lix);
999: }
1000: ISLocalToGlobalMappingApplyBlock(x->map->mapping,ni,(PetscInt*)ix,lix);
1001: (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1002: if (ni > 128) {
1003: PetscFree(lix);
1004: }
1005: } else {
1006: (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1007: }
1008: PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1009: PetscObjectStateIncrease((PetscObject)x);
1010: return 0;
1011: }
1013: /*@
1014: VecMTDot - Computes indefinite vector multiple dot products.
1015: That is, it does NOT use the complex conjugate.
1017: Collective on Vec
1019: Input Parameters:
1020: + x - one vector
1021: . nv - number of vectors
1022: - y - array of vectors. Note that vectors are pointers
1024: Output Parameter:
1025: . val - array of the dot products
1027: Notes for Users of Complex Numbers:
1028: For complex vectors, VecMTDot() computes the indefinite form
1029: $ val = (x,y) = y^T x,
1030: where y^T denotes the transpose of y.
1032: Use VecMDot() for the inner product
1033: $ val = (x,y) = y^H x,
1034: where y^H denotes the conjugate transpose of y.
1036: Level: intermediate
1038: .seealso: VecMDot(), VecTDot()
1039: @*/
1040: PetscErrorCode VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1041: {
1044: if (!nv) return 0;
1051: VecCheckSameSize(x,1,*y,3);
1053: PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1054: (*x->ops->mtdot)(x,nv,y,val);
1055: PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1056: return 0;
1057: }
1059: /*@
1060: VecMDot - Computes vector multiple dot products.
1062: Collective on Vec
1064: Input Parameters:
1065: + x - one vector
1066: . nv - number of vectors
1067: - y - array of vectors.
1069: Output Parameter:
1070: . val - array of the dot products (does not allocate the array)
1072: Notes for Users of Complex Numbers:
1073: For complex vectors, VecMDot() computes
1074: $ val = (x,y) = y^H x,
1075: where y^H denotes the conjugate transpose of y.
1077: Use VecMTDot() for the indefinite form
1078: $ val = (x,y) = y^T x,
1079: where y^T denotes the transpose of y.
1081: Level: intermediate
1083: .seealso: VecMTDot(), VecDot()
1084: @*/
1085: PetscErrorCode VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1086: {
1089: if (!nv) return 0;
1097: VecCheckSameSize(x,1,*y,3);
1099: PetscLogEventBegin(VEC_MDot,x,*y,0,0);
1100: (*x->ops->mdot)(x,nv,y,val);
1101: PetscLogEventEnd(VEC_MDot,x,*y,0,0);
1102: return 0;
1103: }
1105: /*@
1106: VecMAXPY - Computes y = y + sum alpha[i] x[i]
1108: Logically Collective on Vec
1110: Input Parameters:
1111: + nv - number of scalars and x-vectors
1112: . alpha - array of scalars
1113: . y - one vector
1114: - x - array of vectors
1116: Level: intermediate
1118: Notes:
1119: y cannot be any of the x vectors
1121: .seealso: VecAYPX(), VecWAXPY(), VecAXPY(), VecAXPBYPCZ(), VecAXPBY()
1122: @*/
1123: PetscErrorCode VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1124: {
1125: PetscInt i;
1126: PetscBool nonzero;
1130: if (!nv) return 0;
1138: VecCheckSameSize(y,1,*x,4);
1140: for (i=0, nonzero = PETSC_FALSE; i<nv && !nonzero; i++) nonzero = (PetscBool)(nonzero || alpha[i] != (PetscScalar)0.0);
1141: if (!nonzero) return 0;
1142: VecSetErrorIfLocked(y,1);
1143: PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1144: (*y->ops->maxpy)(y,nv,alpha,x);
1145: PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1146: PetscObjectStateIncrease((PetscObject)y);
1147: return 0;
1148: }
1150: /*@
1151: VecConcatenate - Creates a new vector that is a vertical concatenation of all the given array of vectors
1152: in the order they appear in the array. The concatenated vector resides on the same
1153: communicator and is the same type as the source vectors.
1155: Collective on X
1157: Input Parameters:
1158: + nx - number of vectors to be concatenated
1159: - X - array containing the vectors to be concatenated in the order of concatenation
1161: Output Parameters:
1162: + Y - concatenated vector
1163: - x_is - array of index sets corresponding to the concatenated components of Y (NULL if not needed)
1165: Notes:
1166: Concatenation is similar to the functionality of a VecNest object; they both represent combination of
1167: different vector spaces. However, concatenated vectors do not store any information about their
1168: sub-vectors and own their own data. Consequently, this function provides index sets to enable the
1169: manipulation of data in the concatenated vector that corresponds to the original components at creation.
1171: This is a useful tool for outer loop algorithms, particularly constrained optimizers, where the solver
1172: has to operate on combined vector spaces and cannot utilize VecNest objects due to incompatibility with
1173: bound projections.
1175: Level: advanced
1177: .seealso: VECNEST, VECSCATTER, VecScatterCreate()
1178: @*/
1179: PetscErrorCode VecConcatenate(PetscInt nx, const Vec X[], Vec *Y, IS *x_is[])
1180: {
1181: MPI_Comm comm;
1182: VecType vec_type;
1183: Vec Ytmp, Xtmp;
1184: IS *is_tmp;
1185: PetscInt i, shift=0, Xnl, Xng, Xbegin;
1192: if ((*X)->ops->concatenate) {
1193: /* use the dedicated concatenation function if available */
1194: (*(*X)->ops->concatenate)(nx,X,Y,x_is);
1195: } else {
1196: /* loop over vectors and start creating IS */
1197: comm = PetscObjectComm((PetscObject)(*X));
1198: VecGetType(*X, &vec_type);
1199: PetscMalloc1(nx, &is_tmp);
1200: for (i=0; i<nx; i++) {
1201: VecGetSize(X[i], &Xng);
1202: VecGetLocalSize(X[i], &Xnl);
1203: VecGetOwnershipRange(X[i], &Xbegin, NULL);
1204: ISCreateStride(comm, Xnl, shift + Xbegin, 1, &is_tmp[i]);
1205: shift += Xng;
1206: }
1207: /* create the concatenated vector */
1208: VecCreate(comm, &Ytmp);
1209: VecSetType(Ytmp, vec_type);
1210: VecSetSizes(Ytmp, PETSC_DECIDE, shift);
1211: VecSetUp(Ytmp);
1212: /* copy data from X array to Y and return */
1213: for (i=0; i<nx; i++) {
1214: VecGetSubVector(Ytmp, is_tmp[i], &Xtmp);
1215: VecCopy(X[i], Xtmp);
1216: VecRestoreSubVector(Ytmp, is_tmp[i], &Xtmp);
1217: }
1218: *Y = Ytmp;
1219: if (x_is) {
1220: *x_is = is_tmp;
1221: } else {
1222: for (i=0; i<nx; i++) {
1223: ISDestroy(&is_tmp[i]);
1224: }
1225: PetscFree(is_tmp);
1226: }
1227: }
1228: return 0;
1229: }
1231: /* A helper function for VecGetSubVector to check if we can implement it with no-copy (i.e. the subvector shares
1232: memory with the original vector), and the block size of the subvector.
1234: Input Parameters:
1235: + X - the original vector
1236: - is - the index set of the subvector
1238: Output Parameters:
1239: + contig - PETSC_TRUE if the index set refers to contiguous entries on this process, else PETSC_FALSE
1240: . start - start of contiguous block, as an offset from the start of the ownership range of the original vector
1241: - blocksize - the block size of the subvector
1243: */
1244: PetscErrorCode VecGetSubVectorContiguityAndBS_Private(Vec X,IS is,PetscBool *contig,PetscInt *start,PetscInt *blocksize)
1245: {
1246: PetscInt gstart,gend,lstart;
1247: PetscBool red[2] = {PETSC_TRUE/*contiguous*/,PETSC_TRUE/*validVBS*/};
1248: PetscInt n,N,ibs,vbs,bs = -1;
1250: ISGetLocalSize(is,&n);
1251: ISGetSize(is,&N);
1252: ISGetBlockSize(is,&ibs);
1253: VecGetBlockSize(X,&vbs);
1254: VecGetOwnershipRange(X,&gstart,&gend);
1255: ISContiguousLocal(is,gstart,gend,&lstart,&red[0]);
1256: /* block size is given by IS if ibs > 1; otherwise, check the vector */
1257: if (ibs > 1) {
1258: MPIU_Allreduce(MPI_IN_PLACE,red,1,MPIU_BOOL,MPI_LAND,PetscObjectComm((PetscObject)is));
1259: bs = ibs;
1260: } else {
1261: if (n%vbs || vbs == 1) red[1] = PETSC_FALSE; /* this process invalidate the collectiveness of block size */
1262: MPIU_Allreduce(MPI_IN_PLACE,red,2,MPIU_BOOL,MPI_LAND,PetscObjectComm((PetscObject)is));
1263: if (red[0] && red[1]) bs = vbs; /* all processes have a valid block size and the access will be contiguous */
1264: }
1266: *contig = red[0];
1267: *start = lstart;
1268: *blocksize = bs;
1269: return 0;
1270: }
1272: /* A helper function for VecGetSubVector, to be used when we have to build a standalone subvector through VecScatter
1274: Input Parameters:
1275: + X - the original vector
1276: . is - the index set of the subvector
1277: - bs - the block size of the subvector, gotten from VecGetSubVectorContiguityAndBS_Private()
1279: Output Parameters:
1280: . Z - the subvector, which will compose the VecScatter context on output
1281: */
1282: PetscErrorCode VecGetSubVectorThroughVecScatter_Private(Vec X,IS is,PetscInt bs,Vec *Z)
1283: {
1284: PetscInt n,N;
1285: VecScatter vscat;
1286: Vec Y;
1288: ISGetLocalSize(is,&n);
1289: ISGetSize(is,&N);
1290: VecCreate(PetscObjectComm((PetscObject)is),&Y);
1291: VecSetSizes(Y,n,N);
1292: VecSetBlockSize(Y,bs);
1293: VecSetType(Y,((PetscObject)X)->type_name);
1294: VecScatterCreate(X,is,Y,NULL,&vscat);
1295: VecScatterBegin(vscat,X,Y,INSERT_VALUES,SCATTER_FORWARD);
1296: VecScatterEnd(vscat,X,Y,INSERT_VALUES,SCATTER_FORWARD);
1297: PetscObjectCompose((PetscObject)Y,"VecGetSubVector_Scatter",(PetscObject)vscat);
1298: VecScatterDestroy(&vscat);
1299: *Z = Y;
1300: return 0;
1301: }
1303: /*@
1304: VecGetSubVector - Gets a vector representing part of another vector
1306: Collective on X and IS
1308: Input Parameters:
1309: + X - vector from which to extract a subvector
1310: - is - index set representing portion of X to extract
1312: Output Parameter:
1313: . Y - subvector corresponding to is
1315: Level: advanced
1317: Notes:
1318: The subvector Y should be returned with VecRestoreSubVector().
1319: X and is must be defined on the same communicator
1321: This function may return a subvector without making a copy, therefore it is not safe to use the original vector while
1322: modifying the subvector. Other non-overlapping subvectors can still be obtained from X using this function.
1323: The resulting subvector inherits the block size from the IS if greater than one. Otherwise, the block size is guessed from the block size of the original vec.
1325: .seealso: MatCreateSubMatrix()
1326: @*/
1327: PetscErrorCode VecGetSubVector(Vec X,IS is,Vec *Y)
1328: {
1329: Vec Z;
1335: if (X->ops->getsubvector) {
1336: (*X->ops->getsubvector)(X,is,&Z);
1337: } else { /* Default implementation currently does no caching */
1338: PetscBool contig;
1339: PetscInt n,N,start,bs;
1341: ISGetLocalSize(is,&n);
1342: ISGetSize(is,&N);
1343: VecGetSubVectorContiguityAndBS_Private(X,is,&contig,&start,&bs);
1344: if (contig) { /* We can do a no-copy implementation */
1345: const PetscScalar *x;
1346: PetscInt state = 0;
1347: PetscBool isstd,iscuda,iship;
1349: PetscObjectTypeCompareAny((PetscObject)X,&isstd,VECSEQ,VECMPI,VECSTANDARD,"");
1350: PetscObjectTypeCompareAny((PetscObject)X,&iscuda,VECSEQCUDA,VECMPICUDA,"");
1351: PetscObjectTypeCompareAny((PetscObject)X,&iship,VECSEQHIP,VECMPIHIP,"");
1352: if (iscuda) {
1353: #if defined(PETSC_HAVE_CUDA)
1354: const PetscScalar *x_d;
1355: PetscMPIInt size;
1356: PetscOffloadMask flg;
1358: VecCUDAGetArrays_Private(X,&x,&x_d,&flg);
1361: if (x) x += start;
1362: if (x_d) x_d += start;
1363: MPI_Comm_size(PetscObjectComm((PetscObject)X),&size);
1364: if (size == 1) {
1365: VecCreateSeqCUDAWithArrays(PetscObjectComm((PetscObject)X),bs,n,x,x_d,&Z);
1366: } else {
1367: VecCreateMPICUDAWithArrays(PetscObjectComm((PetscObject)X),bs,n,N,x,x_d,&Z);
1368: }
1369: Z->offloadmask = flg;
1370: #endif
1371: } else if (iship) {
1372: #if defined(PETSC_HAVE_HIP)
1373: const PetscScalar *x_d;
1374: PetscMPIInt size;
1375: PetscOffloadMask flg;
1377: VecHIPGetArrays_Private(X,&x,&x_d,&flg);
1380: if (x) x += start;
1381: if (x_d) x_d += start;
1382: MPI_Comm_size(PetscObjectComm((PetscObject)X),&size);
1383: if (size == 1) {
1384: VecCreateSeqHIPWithArrays(PetscObjectComm((PetscObject)X),bs,n,x,x_d,&Z);
1385: } else {
1386: VecCreateMPIHIPWithArrays(PetscObjectComm((PetscObject)X),bs,n,N,x,x_d,&Z);
1387: }
1388: Z->offloadmask = flg;
1389: #endif
1390: } else if (isstd) {
1391: PetscMPIInt size;
1393: MPI_Comm_size(PetscObjectComm((PetscObject)X),&size);
1394: VecGetArrayRead(X,&x);
1395: if (x) x += start;
1396: if (size == 1) {
1397: VecCreateSeqWithArray(PetscObjectComm((PetscObject)X),bs,n,x,&Z);
1398: } else {
1399: VecCreateMPIWithArray(PetscObjectComm((PetscObject)X),bs,n,N,x,&Z);
1400: }
1401: VecRestoreArrayRead(X,&x);
1402: } else { /* default implementation: use place array */
1403: VecGetArrayRead(X,&x);
1404: VecCreate(PetscObjectComm((PetscObject)X),&Z);
1405: VecSetType(Z,((PetscObject)X)->type_name);
1406: VecSetSizes(Z,n,N);
1407: VecSetBlockSize(Z,bs);
1408: VecPlaceArray(Z,x ? x+start : NULL);
1409: VecRestoreArrayRead(X,&x);
1410: }
1412: /* this is relevant only in debug mode */
1413: VecLockGet(X,&state);
1414: if (state) {
1415: VecLockReadPush(Z);
1416: }
1417: Z->ops->placearray = NULL;
1418: Z->ops->replacearray = NULL;
1419: } else { /* Have to create a scatter and do a copy */
1420: VecGetSubVectorThroughVecScatter_Private(X,is,bs,&Z);
1421: }
1422: }
1423: /* Record the state when the subvector was gotten so we know whether its values need to be put back */
1424: if (VecGetSubVectorSavedStateId < 0) PetscObjectComposedDataRegister(&VecGetSubVectorSavedStateId);
1425: PetscObjectComposedDataSetInt((PetscObject)Z,VecGetSubVectorSavedStateId,1);
1426: *Y = Z;
1427: return 0;
1428: }
1430: /*@
1431: VecRestoreSubVector - Restores a subvector extracted using VecGetSubVector()
1433: Collective on IS
1435: Input Parameters:
1436: + X - vector from which subvector was obtained
1437: . is - index set representing the subset of X
1438: - Y - subvector being restored
1440: Level: advanced
1442: .seealso: VecGetSubVector()
1443: @*/
1444: PetscErrorCode VecRestoreSubVector(Vec X,IS is,Vec *Y)
1445: {
1446: PETSC_UNUSED PetscObjectState dummystate = 0;
1447: PetscBool unchanged;
1455: if (X->ops->restoresubvector) {
1456: (*X->ops->restoresubvector)(X,is,Y);
1457: } else {
1458: PetscObjectComposedDataGetInt((PetscObject)*Y,VecGetSubVectorSavedStateId,dummystate,unchanged);
1459: if (!unchanged) { /* If Y's state has not changed since VecGetSubVector(), we only need to destroy Y */
1460: VecScatter scatter;
1461: PetscInt state;
1463: VecLockGet(X,&state);
1466: PetscObjectQuery((PetscObject)*Y,"VecGetSubVector_Scatter",(PetscObject*)&scatter);
1467: if (scatter) {
1468: VecScatterBegin(scatter,*Y,X,INSERT_VALUES,SCATTER_REVERSE);
1469: VecScatterEnd(scatter,*Y,X,INSERT_VALUES,SCATTER_REVERSE);
1470: } else {
1471: PetscBool iscuda,iship;
1472: PetscObjectTypeCompareAny((PetscObject)X,&iscuda,VECSEQCUDA,VECMPICUDA,"");
1473: PetscObjectTypeCompareAny((PetscObject)X,&iship,VECSEQHIP,VECMPIHIP,"");
1475: if (iscuda) {
1476: #if defined(PETSC_HAVE_CUDA)
1477: PetscOffloadMask ymask = (*Y)->offloadmask;
1479: /* The offloadmask of X dictates where to move memory
1480: If X GPU data is valid, then move Y data on GPU if needed
1481: Otherwise, move back to the CPU */
1482: switch (X->offloadmask) {
1483: case PETSC_OFFLOAD_BOTH:
1484: if (ymask == PETSC_OFFLOAD_CPU) {
1485: VecCUDAResetArray(*Y);
1486: } else if (ymask == PETSC_OFFLOAD_GPU) {
1487: X->offloadmask = PETSC_OFFLOAD_GPU;
1488: }
1489: break;
1490: case PETSC_OFFLOAD_GPU:
1491: if (ymask == PETSC_OFFLOAD_CPU) {
1492: VecCUDAResetArray(*Y);
1493: }
1494: break;
1495: case PETSC_OFFLOAD_CPU:
1496: if (ymask == PETSC_OFFLOAD_GPU) {
1497: VecResetArray(*Y);
1498: }
1499: break;
1500: case PETSC_OFFLOAD_UNALLOCATED:
1501: case PETSC_OFFLOAD_KOKKOS:
1502: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"This should not happen");
1503: }
1504: #endif
1505: } else if (iship) {
1506: #if defined(PETSC_HAVE_HIP)
1507: PetscOffloadMask ymask = (*Y)->offloadmask;
1509: /* The offloadmask of X dictates where to move memory
1510: If X GPU data is valid, then move Y data on GPU if needed
1511: Otherwise, move back to the CPU */
1512: switch (X->offloadmask) {
1513: case PETSC_OFFLOAD_BOTH:
1514: if (ymask == PETSC_OFFLOAD_CPU) {
1515: VecHIPResetArray(*Y);
1516: } else if (ymask == PETSC_OFFLOAD_GPU) {
1517: X->offloadmask = PETSC_OFFLOAD_GPU;
1518: }
1519: break;
1520: case PETSC_OFFLOAD_GPU:
1521: if (ymask == PETSC_OFFLOAD_CPU) {
1522: VecHIPResetArray(*Y);
1523: }
1524: break;
1525: case PETSC_OFFLOAD_CPU:
1526: if (ymask == PETSC_OFFLOAD_GPU) {
1527: VecResetArray(*Y);
1528: }
1529: break;
1530: case PETSC_OFFLOAD_UNALLOCATED:
1531: case PETSC_OFFLOAD_KOKKOS:
1532: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"This should not happen");
1533: }
1534: #endif
1535: } else {
1536: /* If OpenCL vecs updated the device memory, this triggers a copy on the CPU */
1537: VecResetArray(*Y);
1538: }
1539: PetscObjectStateIncrease((PetscObject)X);
1540: }
1541: }
1542: }
1543: VecDestroy(Y);
1544: return 0;
1545: }
1547: /*@
1548: VecGetLocalVectorRead - Maps the local portion of a vector into a
1549: vector. You must call VecRestoreLocalVectorRead() when the local
1550: vector is no longer needed.
1552: Not collective.
1554: Input parameter:
1555: . v - The vector for which the local vector is desired.
1557: Output parameter:
1558: . w - Upon exit this contains the local vector.
1560: Level: beginner
1562: Notes:
1563: This function is similar to VecGetArrayRead() which maps the local
1564: portion into a raw pointer. VecGetLocalVectorRead() is usually
1565: almost as efficient as VecGetArrayRead() but in certain circumstances
1566: VecGetLocalVectorRead() can be much more efficient than
1567: VecGetArrayRead(). This is because the construction of a contiguous
1568: array representing the vector data required by VecGetArrayRead() can
1569: be an expensive operation for certain vector types. For example, for
1570: GPU vectors VecGetArrayRead() requires that the data between device
1571: and host is synchronized.
1573: Unlike VecGetLocalVector(), this routine is not collective and
1574: preserves cached information.
1576: .seealso: VecRestoreLocalVectorRead(), VecGetLocalVector(), VecGetArrayRead(), VecGetArray()
1577: @*/
1578: PetscErrorCode VecGetLocalVectorRead(Vec v,Vec w)
1579: {
1580: PetscScalar *a;
1584: VecCheckSameLocalSize(v,1,w,2);
1585: if (v->ops->getlocalvectorread) {
1586: (*v->ops->getlocalvectorread)(v,w);
1587: } else {
1588: VecGetArrayRead(v,(const PetscScalar**)&a);
1589: VecPlaceArray(w,a);
1590: }
1591: PetscObjectStateIncrease((PetscObject)w);
1592: VecLockReadPush(v);
1593: VecLockReadPush(w);
1594: return 0;
1595: }
1597: /*@
1598: VecRestoreLocalVectorRead - Unmaps the local portion of a vector
1599: previously mapped into a vector using VecGetLocalVectorRead().
1601: Not collective.
1603: Input parameter:
1604: + v - The local portion of this vector was previously mapped into w using VecGetLocalVectorRead().
1605: - w - The vector into which the local portion of v was mapped.
1607: Level: beginner
1609: .seealso: VecGetLocalVectorRead(), VecGetLocalVector(), VecGetArrayRead(), VecGetArray()
1610: @*/
1611: PetscErrorCode VecRestoreLocalVectorRead(Vec v,Vec w)
1612: {
1613: PetscScalar *a;
1617: if (v->ops->restorelocalvectorread) {
1618: (*v->ops->restorelocalvectorread)(v,w);
1619: } else {
1620: VecGetArrayRead(w,(const PetscScalar**)&a);
1621: VecRestoreArrayRead(v,(const PetscScalar**)&a);
1622: VecResetArray(w);
1623: }
1624: VecLockReadPop(v);
1625: VecLockReadPop(w);
1626: PetscObjectStateIncrease((PetscObject)w);
1627: return 0;
1628: }
1630: /*@
1631: VecGetLocalVector - Maps the local portion of a vector into a
1632: vector.
1634: Collective on v, not collective on w.
1636: Input parameter:
1637: . v - The vector for which the local vector is desired.
1639: Output parameter:
1640: . w - Upon exit this contains the local vector.
1642: Level: beginner
1644: Notes:
1645: This function is similar to VecGetArray() which maps the local
1646: portion into a raw pointer. VecGetLocalVector() is usually about as
1647: efficient as VecGetArray() but in certain circumstances
1648: VecGetLocalVector() can be much more efficient than VecGetArray().
1649: This is because the construction of a contiguous array representing
1650: the vector data required by VecGetArray() can be an expensive
1651: operation for certain vector types. For example, for GPU vectors
1652: VecGetArray() requires that the data between device and host is
1653: synchronized.
1655: .seealso: VecRestoreLocalVector(), VecGetLocalVectorRead(), VecGetArrayRead(), VecGetArray()
1656: @*/
1657: PetscErrorCode VecGetLocalVector(Vec v,Vec w)
1658: {
1659: PetscScalar *a;
1663: VecCheckSameLocalSize(v,1,w,2);
1664: if (v->ops->getlocalvector) {
1665: (*v->ops->getlocalvector)(v,w);
1666: } else {
1667: VecGetArray(v,&a);
1668: VecPlaceArray(w,a);
1669: }
1670: PetscObjectStateIncrease((PetscObject)w);
1671: return 0;
1672: }
1674: /*@
1675: VecRestoreLocalVector - Unmaps the local portion of a vector
1676: previously mapped into a vector using VecGetLocalVector().
1678: Logically collective.
1680: Input parameter:
1681: + v - The local portion of this vector was previously mapped into w using VecGetLocalVector().
1682: - w - The vector into which the local portion of v was mapped.
1684: Level: beginner
1686: .seealso: VecGetLocalVector(), VecGetLocalVectorRead(), VecRestoreLocalVectorRead(), LocalVectorRead(), VecGetArrayRead(), VecGetArray()
1687: @*/
1688: PetscErrorCode VecRestoreLocalVector(Vec v,Vec w)
1689: {
1690: PetscScalar *a;
1694: if (v->ops->restorelocalvector) {
1695: (*v->ops->restorelocalvector)(v,w);
1696: } else {
1697: VecGetArray(w,&a);
1698: VecRestoreArray(v,&a);
1699: VecResetArray(w);
1700: }
1701: PetscObjectStateIncrease((PetscObject)w);
1702: PetscObjectStateIncrease((PetscObject)v);
1703: return 0;
1704: }
1706: /*@C
1707: VecGetArray - Returns a pointer to a contiguous array that contains this
1708: processor's portion of the vector data. For the standard PETSc
1709: vectors, VecGetArray() returns a pointer to the local data array and
1710: does not use any copies. If the underlying vector data is not stored
1711: in a contiguous array this routine will copy the data to a contiguous
1712: array and return a pointer to that. You MUST call VecRestoreArray()
1713: when you no longer need access to the array.
1715: Logically Collective on Vec
1717: Input Parameter:
1718: . x - the vector
1720: Output Parameter:
1721: . a - location to put pointer to the array
1723: Fortran Note:
1724: This routine is used differently from Fortran 77
1725: $ Vec x
1726: $ PetscScalar x_array(1)
1727: $ PetscOffset i_x
1728: $ PetscErrorCode ierr
1729: $ call VecGetArray(x,x_array,i_x,ierr)
1730: $
1731: $ Access first local entry in vector with
1732: $ value = x_array(i_x + 1)
1733: $
1734: $ ...... other code
1735: $ call VecRestoreArray(x,x_array,i_x,ierr)
1736: For Fortran 90 see VecGetArrayF90()
1738: See the Fortran chapter of the users manual and
1739: petsc/src/snes/tutorials/ex5f.F for details.
1741: Level: beginner
1743: .seealso: VecRestoreArray(), VecGetArrayRead(), VecGetArrays(), VecGetArrayF90(), VecGetArrayReadF90(), VecPlaceArray(), VecGetArray2d(),
1744: VecGetArrayPair(), VecRestoreArrayPair(), VecGetArrayWrite(), VecRestoreArrayWrite()
1745: @*/
1746: PetscErrorCode VecGetArray(Vec x,PetscScalar **a)
1747: {
1749: VecSetErrorIfLocked(x,1);
1750: if (x->ops->getarray) { /* The if-else order matters! VECNEST, VECCUDA etc should have ops->getarray while VECCUDA etc are petscnative */
1751: (*x->ops->getarray)(x,a);
1752: } else if (x->petscnative) { /* VECSTANDARD */
1753: *a = *((PetscScalar**)x->data);
1754: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot get array for vector type \"%s\"",((PetscObject)x)->type_name);
1755: return 0;
1756: }
1758: /*@C
1759: VecRestoreArray - Restores a vector after VecGetArray() has been called.
1761: Logically Collective on Vec
1763: Input Parameters:
1764: + x - the vector
1765: - a - location of pointer to array obtained from VecGetArray()
1767: Level: beginner
1769: .seealso: VecGetArray(), VecRestoreArrayRead(), VecRestoreArrays(), VecRestoreArrayF90(), VecRestoreArrayReadF90(), VecPlaceArray(), VecRestoreArray2d(),
1770: VecGetArrayPair(), VecRestoreArrayPair()
1771: @*/
1772: PetscErrorCode VecRestoreArray(Vec x,PetscScalar **a)
1773: {
1775: if (x->ops->restorearray) { /* VECNEST, VECCUDA etc */
1776: (*x->ops->restorearray)(x,a);
1777: } else if (x->petscnative) { /* VECSTANDARD */
1778: /* nothing */
1779: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot restore array for vector type \"%s\"",((PetscObject)x)->type_name);
1780: if (a) *a = NULL;
1781: PetscObjectStateIncrease((PetscObject)x);
1782: return 0;
1783: }
1784: /*@C
1785: VecGetArrayRead - Get read-only pointer to contiguous array containing this processor's portion of the vector data.
1787: Not Collective
1789: Input Parameter:
1790: . x - the vector
1792: Output Parameter:
1793: . a - the array
1795: Level: beginner
1797: Notes:
1798: The array must be returned using a matching call to VecRestoreArrayRead().
1800: Unlike VecGetArray(), this routine is not collective and preserves cached information like vector norms.
1802: Standard PETSc vectors use contiguous storage so that this routine does not perform a copy. Other vector
1803: implementations may require a copy, but must such implementations should cache the contiguous representation so that
1804: only one copy is performed when this routine is called multiple times in sequence.
1806: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
1807: @*/
1808: PetscErrorCode VecGetArrayRead(Vec x,const PetscScalar **a)
1809: {
1811: if (x->ops->getarray) { /* VECNEST, VECCUDA, VECKOKKOS etc */
1812: (*x->ops->getarray)(x,(PetscScalar**)a);
1813: } else if (x->petscnative) { /* VECSTANDARD */
1814: *a = *((PetscScalar**)x->data);
1815: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot get array read for vector type \"%s\"",((PetscObject)x)->type_name);
1816: return 0;
1817: }
1819: /*@C
1820: VecRestoreArrayRead - Restore array obtained with VecGetArrayRead()
1822: Not Collective
1824: Input Parameters:
1825: + vec - the vector
1826: - array - the array
1828: Level: beginner
1830: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
1831: @*/
1832: PetscErrorCode VecRestoreArrayRead(Vec x,const PetscScalar **a)
1833: {
1835: if (x->petscnative) { /* VECSTANDARD, VECCUDA, VECKOKKOS etc */
1836: /* nothing */
1837: } else if (x->ops->restorearrayread) { /* VECNEST */
1838: (*x->ops->restorearrayread)(x,a);
1839: } else { /* No one? */
1840: (*x->ops->restorearray)(x,(PetscScalar**)a);
1841: }
1842: if (a) *a = NULL;
1843: return 0;
1844: }
1846: /*@C
1847: VecGetArrayWrite - Returns a pointer to a contiguous array that WILL contains this
1848: processor's portion of the vector data. The values in this array are NOT valid, the routine calling this
1849: routine is responsible for putting values into the array; any values it does not set will be invalid
1851: Logically Collective on Vec
1853: Input Parameter:
1854: . x - the vector
1856: Output Parameter:
1857: . a - location to put pointer to the array
1859: Level: intermediate
1861: This is for vectors associate with GPUs, the vector is not copied up before giving access. If you need correct
1862: values in the array use VecGetArray()
1864: Concepts: vector^accessing local values
1866: .seealso: VecRestoreArray(), VecGetArrayRead(), VecGetArrays(), VecGetArrayF90(), VecGetArrayReadF90(), VecPlaceArray(), VecGetArray2d(),
1867: VecGetArrayPair(), VecRestoreArrayPair(), VecGetArray(), VecRestoreArrayWrite()
1868: @*/
1869: PetscErrorCode VecGetArrayWrite(Vec x,PetscScalar **a)
1870: {
1872: VecSetErrorIfLocked(x,1);
1873: if (x->ops->getarraywrite) {
1874: (*x->ops->getarraywrite)(x,a);
1875: } else {
1876: VecGetArray(x,a);
1877: }
1878: return 0;
1879: }
1881: /*@C
1882: VecRestoreArrayWrite - Restores a vector after VecGetArrayWrite() has been called.
1884: Logically Collective on Vec
1886: Input Parameters:
1887: + x - the vector
1888: - a - location of pointer to array obtained from VecGetArray()
1890: Level: beginner
1892: .seealso: VecGetArray(), VecRestoreArrayRead(), VecRestoreArrays(), VecRestoreArrayF90(), VecRestoreArrayReadF90(), VecPlaceArray(), VecRestoreArray2d(),
1893: VecGetArrayPair(), VecRestoreArrayPair(), VecGetArrayWrite()
1894: @*/
1895: PetscErrorCode VecRestoreArrayWrite(Vec x,PetscScalar **a)
1896: {
1898: if (x->ops->restorearraywrite) {
1899: (*x->ops->restorearraywrite)(x,a);
1900: } else if (x->ops->restorearray) {
1901: (*x->ops->restorearray)(x,a);
1902: }
1903: if (a) *a = NULL;
1904: PetscObjectStateIncrease((PetscObject)x);
1905: return 0;
1906: }
1908: /*@C
1909: VecGetArrays - Returns a pointer to the arrays in a set of vectors
1910: that were created by a call to VecDuplicateVecs(). You MUST call
1911: VecRestoreArrays() when you no longer need access to the array.
1913: Logically Collective on Vec
1915: Input Parameters:
1916: + x - the vectors
1917: - n - the number of vectors
1919: Output Parameter:
1920: . a - location to put pointer to the array
1922: Fortran Note:
1923: This routine is not supported in Fortran.
1925: Level: intermediate
1927: .seealso: VecGetArray(), VecRestoreArrays()
1928: @*/
1929: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1930: {
1931: PetscInt i;
1932: PetscScalar **q;
1938: PetscMalloc1(n,&q);
1939: for (i=0; i<n; ++i) {
1940: VecGetArray(x[i],&q[i]);
1941: }
1942: *a = q;
1943: return 0;
1944: }
1946: /*@C
1947: VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1948: has been called.
1950: Logically Collective on Vec
1952: Input Parameters:
1953: + x - the vector
1954: . n - the number of vectors
1955: - a - location of pointer to arrays obtained from VecGetArrays()
1957: Notes:
1958: For regular PETSc vectors this routine does not involve any copies. For
1959: any special vectors that do not store local vector data in a contiguous
1960: array, this routine will copy the data back into the underlying
1961: vector data structure from the arrays obtained with VecGetArrays().
1963: Fortran Note:
1964: This routine is not supported in Fortran.
1966: Level: intermediate
1968: .seealso: VecGetArrays(), VecRestoreArray()
1969: @*/
1970: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1971: {
1972: PetscInt i;
1973: PetscScalar **q = *a;
1979: for (i=0; i<n; ++i) {
1980: VecRestoreArray(x[i],&q[i]);
1981: }
1982: PetscFree(q);
1983: return 0;
1984: }
1986: /*@C
1987: VecGetArrayAndMemType - Like VecGetArray(), but if this is a standard device vector (e.g., VECCUDA), the returned pointer will be a device
1988: pointer to the device memory that contains this processor's portion of the vector data. Device data is guaranteed to have the latest value.
1989: Otherwise, when this is a host vector (e.g., VECMPI), this routine functions the same as VecGetArray() and returns a host pointer.
1991: For VECKOKKOS, if Kokkos is configured without device (e.g., use serial or openmp), per this function, the vector works like VECSEQ/VECMPI;
1992: otherwise, it works like VECCUDA or VECHIP etc.
1994: Logically Collective on Vec
1996: Input Parameter:
1997: . x - the vector
1999: Output Parameters:
2000: + a - location to put pointer to the array
2001: - mtype - memory type of the array
2003: Level: beginner
2005: .seealso: VecRestoreArrayAndMemType(), VecGetArrayReadAndMemType(), VecGetArrayWriteAndMemType(), VecRestoreArray(), VecGetArrayRead(), VecGetArrays(), VecGetArrayF90(), VecGetArrayReadF90(),
2006: VecPlaceArray(), VecGetArray2d(), VecGetArrayPair(), VecRestoreArrayPair(), VecGetArrayWrite(), VecRestoreArrayWrite()
2007: @*/
2008: PetscErrorCode VecGetArrayAndMemType(Vec x,PetscScalar **a,PetscMemType *mtype)
2009: {
2010: PetscMemType omtype;
2014: VecSetErrorIfLocked(x,1);
2015: if (x->ops->getarrayandmemtype) { /* VECCUDA, VECKOKKOS etc */
2016: (*x->ops->getarrayandmemtype)(x,a,&omtype);
2017: } else { /* VECSTANDARD, VECNEST, VECVIENNACL */
2018: VecGetArray(x,a);
2019: omtype = PETSC_MEMTYPE_HOST;
2020: }
2021: if (mtype) *mtype = omtype;
2022: return 0;
2023: }
2025: /*@C
2026: VecRestoreArrayAndMemType - Restores a vector after VecGetArrayAndMemType() has been called.
2028: Logically Collective on Vec
2030: Input Parameters:
2031: + x - the vector
2032: - a - location of pointer to array obtained from VecGetArrayAndMemType()
2034: Level: beginner
2036: .seealso: VecGetArrayAndMemType(), VecGetArray(), VecRestoreArrayRead(), VecRestoreArrays(), VecRestoreArrayF90(), VecRestoreArrayReadF90(),
2037: VecPlaceArray(), VecRestoreArray2d(), VecGetArrayPair(), VecRestoreArrayPair()
2038: @*/
2039: PetscErrorCode VecRestoreArrayAndMemType(Vec x,PetscScalar **a)
2040: {
2043: if (x->ops->restorearrayandmemtype) { /* VECCUDA, VECKOKKOS etc */
2044: (*x->ops->restorearrayandmemtype)(x,a);
2045: } else if (x->ops->restorearray) { /* VECNEST, VECVIENNACL */
2046: (*x->ops->restorearray)(x,a);
2047: } /* VECSTANDARD does nothing */
2048: if (a) *a = NULL;
2049: PetscObjectStateIncrease((PetscObject)x);
2050: return 0;
2051: }
2053: /*@C
2054: VecGetArrayReadAndMemType - Like VecGetArrayRead(), but if the input vector is a device vector, it will return a read-only device pointer. The returned pointer is guarenteed to point to up-to-date data. For host vectors, it functions as VecGetArrayRead().
2056: Not Collective
2058: Input Parameter:
2059: . x - the vector
2061: Output Parameters:
2062: + a - the array
2063: - mtype - memory type of the array
2065: Level: beginner
2067: Notes:
2068: The array must be returned using a matching call to VecRestoreArrayReadAndMemType().
2070: .seealso: VecRestoreArrayReadAndMemType(), VecGetArrayAndMemType(), VecGetArrayWriteAndMemType(), VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair(), VecGetArrayAndMemType()
2071: @*/
2072: PetscErrorCode VecGetArrayReadAndMemType(Vec x,const PetscScalar **a,PetscMemType *mtype)
2073: {
2074: PetscMemType omtype;
2078: #if defined(PETSC_USE_DEBUG)
2080: #endif
2082: if (x->ops->getarrayandmemtype) { /* VECCUDA, VECKOKKOS etc, though they are also petscnative */
2083: (*x->ops->getarrayandmemtype)(x,(PetscScalar**)a,&omtype);
2084: } else if (x->ops->getarray) { /* VECNEST, VECVIENNACL */
2085: (*x->ops->getarray)(x,(PetscScalar**)a);
2086: omtype = PETSC_MEMTYPE_HOST;
2087: } else if (x->petscnative) { /* VECSTANDARD */
2088: *a = *((PetscScalar**)x->data);
2089: omtype = PETSC_MEMTYPE_HOST;
2090: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot get array read in place for vector type \"%s\"",((PetscObject)x)->type_name);
2091: if (mtype) *mtype = omtype;
2092: return 0;
2093: }
2095: /*@C
2096: VecRestoreArrayReadAndMemType - Restore array obtained with VecGetArrayReadAndMemType()
2098: Not Collective
2100: Input Parameters:
2101: + vec - the vector
2102: - array - the array
2104: Level: beginner
2106: .seealso: VecGetArrayReadAndMemType(), VecRestoreArrayAndMemType(), VecRestoreArrayWriteAndMemType(), VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
2107: @*/
2108: PetscErrorCode VecRestoreArrayReadAndMemType(Vec x,const PetscScalar **a)
2109: {
2112: if (x->petscnative) { /* VECSTANDARD, VECCUDA, VECKOKKOS, VECVIENNACL etc */
2113: /* nothing */
2114: } else if (x->ops->restorearrayread) { /* VECNEST */
2115: (*x->ops->restorearrayread)(x,a);
2116: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot restore array read in place for vector type \"%s\"",((PetscObject)x)->type_name);
2117: if (a) *a = NULL;
2118: return 0;
2119: }
2121: /*@C
2122: VecGetArrayWriteAndMemType - Like VecGetArrayWrite(), but if this is a device vector it will aways return
2123: a device pointer to the device memory that contains this processor's portion of the vector data.
2125: Not Collective
2127: Input Parameter:
2128: . x - the vector
2130: Output Parameters:
2131: + a - the array
2132: - mtype - memory type of the array
2134: Level: beginner
2136: Notes:
2137: The array must be returned using a matching call to VecRestoreArrayWriteAndMemType(), where it will label the device memory as most recent.
2139: .seealso: VecRestoreArrayWriteAndMemType(), VecGetArrayReadAndMemType(), VecGetArrayAndMemType(), VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair(),
2140: @*/
2141: PetscErrorCode VecGetArrayWriteAndMemType(Vec x,PetscScalar **a,PetscMemType *mtype)
2142: {
2143: PetscMemType omtype;
2147: if (x->ops->getarraywriteandmemtype) { /* VECCUDA, VECHIP, VECKOKKOS etc, though they are also petscnative */
2148: (*x->ops->getarrayandmemtype)(x,a,&omtype);
2149: } else if (x->ops->getarraywrite) { /* VECNEST, VECVIENNACL */
2150: (*x->ops->getarraywrite)(x,a);
2151: omtype = PETSC_MEMTYPE_HOST;
2152: } else if (x->petscnative) { /* VECSTANDARD */
2153: *a = *((PetscScalar**)x->data);
2154: omtype = PETSC_MEMTYPE_HOST;
2155: } else SETERRQ(PetscObjectComm((PetscObject)x),PETSC_ERR_SUP,"Cannot get array read in place for vector type \"%s\"",((PetscObject)x)->type_name);
2156: if (mtype) *mtype = omtype;
2157: return 0;
2158: }
2160: /*@C
2161: VecRestoreArrayWriteAndMemType - Restore array obtained with VecGetArrayWriteAndMemType()
2163: Not Collective
2165: Input Parameters:
2166: + vec - the vector
2167: - array - the array
2169: Level: beginner
2171: .seealso: VecGetArrayWriteAndMemType(), VecRestoreArrayAndMemType(), VecGetArray(), VecRestoreArray(), VecGetArrayPair(), VecRestoreArrayPair()
2172: @*/
2173: PetscErrorCode VecRestoreArrayWriteAndMemType(Vec x,PetscScalar **a)
2174: {
2175: VecRestoreArrayAndMemType(x,a);
2176: return 0;
2177: }
2179: /*@
2180: VecPlaceArray - Allows one to replace the array in a vector with an
2181: array provided by the user. This is useful to avoid copying an array
2182: into a vector.
2184: Not Collective
2186: Input Parameters:
2187: + vec - the vector
2188: - array - the array
2190: Notes:
2191: You can return to the original array with a call to VecResetArray()
2193: Level: developer
2195: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()
2197: @*/
2198: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
2199: {
2203: if (vec->ops->placearray) {
2204: (*vec->ops->placearray)(vec,array);
2205: } else SETERRQ(PetscObjectComm((PetscObject)vec),PETSC_ERR_SUP,"Cannot place array in this type of vector");
2206: PetscObjectStateIncrease((PetscObject)vec);
2207: return 0;
2208: }
2210: /*@C
2211: VecReplaceArray - Allows one to replace the array in a vector with an
2212: array provided by the user. This is useful to avoid copying an array
2213: into a vector.
2215: Not Collective
2217: Input Parameters:
2218: + vec - the vector
2219: - array - the array
2221: Notes:
2222: This permanently replaces the array and frees the memory associated
2223: with the old array.
2225: The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2226: freed by the user. It will be freed when the vector is destroyed.
2228: Not supported from Fortran
2230: Level: developer
2232: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()
2234: @*/
2235: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
2236: {
2239: if (vec->ops->replacearray) {
2240: (*vec->ops->replacearray)(vec,array);
2241: } else SETERRQ(PetscObjectComm((PetscObject)vec),PETSC_ERR_SUP,"Cannot replace array in this type of vector");
2242: PetscObjectStateIncrease((PetscObject)vec);
2243: return 0;
2244: }
2246: /*@C
2247: VecCUDAGetArray - Provides access to the CUDA buffer inside a vector.
2249: This function has semantics similar to VecGetArray(): the pointer
2250: returned by this function points to a consistent view of the vector
2251: data. This may involve a copy operation of data from the host to the
2252: device if the data on the device is out of date. If the device
2253: memory hasn't been allocated previously it will be allocated as part
2254: of this function call. VecCUDAGetArray() assumes that
2255: the user will modify the vector data. This is similar to
2256: intent(inout) in fortran.
2258: The CUDA device pointer has to be released by calling
2259: VecCUDARestoreArray(). Upon restoring the vector data
2260: the data on the host will be marked as out of date. A subsequent
2261: access of the host data will thus incur a data transfer from the
2262: device to the host.
2264: Input Parameter:
2265: . v - the vector
2267: Output Parameter:
2268: . a - the CUDA device pointer
2270: Fortran note:
2271: This function is not currently available from Fortran.
2273: Level: intermediate
2275: .seealso: VecCUDARestoreArray(), VecCUDAGetArrayRead(), VecCUDAGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2276: @*/
2277: PETSC_EXTERN PetscErrorCode VecCUDAGetArray(Vec v, PetscScalar **a)
2278: {
2280: #if defined(PETSC_HAVE_CUDA)
2281: {
2282: VecCUDACopyToGPU(v);
2283: *a = ((Vec_CUDA*)v->spptr)->GPUarray;
2284: }
2285: #endif
2286: return 0;
2287: }
2289: /*@C
2290: VecCUDARestoreArray - Restore a CUDA device pointer previously acquired with VecCUDAGetArray().
2292: This marks the host data as out of date. Subsequent access to the
2293: vector data on the host side with for instance VecGetArray() incurs a
2294: data transfer.
2296: Input Parameters:
2297: + v - the vector
2298: - a - the CUDA device pointer. This pointer is invalid after
2299: VecCUDARestoreArray() returns.
2301: Fortran note:
2302: This function is not currently available from Fortran.
2304: Level: intermediate
2306: .seealso: VecCUDAGetArray(), VecCUDAGetArrayRead(), VecCUDAGetArrayWrite(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2307: @*/
2308: PETSC_EXTERN PetscErrorCode VecCUDARestoreArray(Vec v, PetscScalar **a)
2309: {
2311: #if defined(PETSC_HAVE_CUDA)
2312: v->offloadmask = PETSC_OFFLOAD_GPU;
2313: #endif
2314: PetscObjectStateIncrease((PetscObject)v);
2315: return 0;
2316: }
2318: /*@C
2319: VecCUDAGetArrayRead - Provides read access to the CUDA buffer inside a vector.
2321: This function is analogous to VecGetArrayRead(): The pointer
2322: returned by this function points to a consistent view of the vector
2323: data. This may involve a copy operation of data from the host to the
2324: device if the data on the device is out of date. If the device
2325: memory hasn't been allocated previously it will be allocated as part
2326: of this function call. VecCUDAGetArrayRead() assumes that the
2327: user will not modify the vector data. This is analgogous to
2328: intent(in) in Fortran.
2330: The CUDA device pointer has to be released by calling
2331: VecCUDARestoreArrayRead(). If the data on the host side was
2332: previously up to date it will remain so, i.e. data on both the device
2333: and the host is up to date. Accessing data on the host side does not
2334: incur a device to host data transfer.
2336: Input Parameter:
2337: . v - the vector
2339: Output Parameter:
2340: . a - the CUDA pointer.
2342: Fortran note:
2343: This function is not currently available from Fortran.
2345: Level: intermediate
2347: .seealso: VecCUDARestoreArrayRead(), VecCUDAGetArray(), VecCUDAGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2348: @*/
2349: PETSC_EXTERN PetscErrorCode VecCUDAGetArrayRead(Vec v,const PetscScalar** a)
2350: {
2351: VecCUDAGetArray(v,(PetscScalar**)a);
2352: return 0;
2353: }
2355: /*@C
2356: VecCUDARestoreArrayRead - Restore a CUDA device pointer previously acquired with VecCUDAGetArrayRead().
2358: If the data on the host side was previously up to date it will remain
2359: so, i.e. data on both the device and the host is up to date.
2360: Accessing data on the host side e.g. with VecGetArray() does not
2361: incur a device to host data transfer.
2363: Input Parameters:
2364: + v - the vector
2365: - a - the CUDA device pointer. This pointer is invalid after
2366: VecCUDARestoreArrayRead() returns.
2368: Fortran note:
2369: This function is not currently available from Fortran.
2371: Level: intermediate
2373: .seealso: VecCUDAGetArrayRead(), VecCUDAGetArrayWrite(), VecCUDAGetArray(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2374: @*/
2375: PETSC_EXTERN PetscErrorCode VecCUDARestoreArrayRead(Vec v, const PetscScalar **a)
2376: {
2378: *a = NULL;
2379: return 0;
2380: }
2382: /*@C
2383: VecCUDAGetArrayWrite - Provides write access to the CUDA buffer inside a vector.
2385: The data pointed to by the device pointer is uninitialized. The user
2386: may not read from this data. Furthermore, the entire array needs to
2387: be filled by the user to obtain well-defined behaviour. The device
2388: memory will be allocated by this function if it hasn't been allocated
2389: previously. This is analogous to intent(out) in Fortran.
2391: The device pointer needs to be released with
2392: VecCUDARestoreArrayWrite(). When the pointer is released the
2393: host data of the vector is marked as out of data. Subsequent access
2394: of the host data with e.g. VecGetArray() incurs a device to host data
2395: transfer.
2397: Input Parameter:
2398: . v - the vector
2400: Output Parameter:
2401: . a - the CUDA pointer
2403: Fortran note:
2404: This function is not currently available from Fortran.
2406: Level: advanced
2408: .seealso: VecCUDARestoreArrayWrite(), VecCUDAGetArray(), VecCUDAGetArrayRead(), VecCUDAGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2409: @*/
2410: PETSC_EXTERN PetscErrorCode VecCUDAGetArrayWrite(Vec v, PetscScalar **a)
2411: {
2413: #if defined(PETSC_HAVE_CUDA)
2414: {
2415: VecCUDAAllocateCheck(v);
2416: *a = ((Vec_CUDA*)v->spptr)->GPUarray;
2417: }
2418: #endif
2419: return 0;
2420: }
2422: /*@C
2423: VecCUDARestoreArrayWrite - Restore a CUDA device pointer previously acquired with VecCUDAGetArrayWrite().
2425: Data on the host will be marked as out of date. Subsequent access of
2426: the data on the host side e.g. with VecGetArray() will incur a device
2427: to host data transfer.
2429: Input Parameters:
2430: + v - the vector
2431: - a - the CUDA device pointer. This pointer is invalid after
2432: VecCUDARestoreArrayWrite() returns.
2434: Fortran note:
2435: This function is not currently available from Fortran.
2437: Level: intermediate
2439: .seealso: VecCUDAGetArrayWrite(), VecCUDAGetArray(), VecCUDAGetArrayRead(), VecCUDAGetArrayWrite(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2440: @*/
2441: PETSC_EXTERN PetscErrorCode VecCUDARestoreArrayWrite(Vec v, PetscScalar **a)
2442: {
2444: #if defined(PETSC_HAVE_CUDA)
2445: v->offloadmask = PETSC_OFFLOAD_GPU;
2446: if (a) *a = NULL;
2447: #endif
2448: PetscObjectStateIncrease((PetscObject)v);
2449: return 0;
2450: }
2452: /*@C
2453: VecCUDAPlaceArray - Allows one to replace the GPU array in a vector with a
2454: GPU array provided by the user. This is useful to avoid copying an
2455: array into a vector.
2457: Not Collective
2459: Input Parameters:
2460: + vec - the vector
2461: - array - the GPU array
2463: Notes:
2464: You can return to the original GPU array with a call to VecCUDAResetArray()
2465: It is not possible to use VecCUDAPlaceArray() and VecPlaceArray() at the
2466: same time on the same vector.
2468: Level: developer
2470: .seealso: VecPlaceArray(), VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray(), VecCUDAResetArray(), VecCUDAReplaceArray()
2472: @*/
2473: PetscErrorCode VecCUDAPlaceArray(Vec vin,const PetscScalar a[])
2474: {
2476: #if defined(PETSC_HAVE_CUDA)
2477: VecCUDACopyToGPU(vin);
2479: ((Vec_Seq*)vin->data)->unplacedarray = (PetscScalar *) ((Vec_CUDA*)vin->spptr)->GPUarray; /* save previous GPU array so reset can bring it back */
2480: ((Vec_CUDA*)vin->spptr)->GPUarray = (PetscScalar*)a;
2481: vin->offloadmask = PETSC_OFFLOAD_GPU;
2482: #endif
2483: PetscObjectStateIncrease((PetscObject)vin);
2484: return 0;
2485: }
2487: /*@C
2488: VecCUDAReplaceArray - Allows one to replace the GPU array in a vector
2489: with a GPU array provided by the user. This is useful to avoid copying
2490: a GPU array into a vector.
2492: Not Collective
2494: Input Parameters:
2495: + vec - the vector
2496: - array - the GPU array
2498: Notes:
2499: This permanently replaces the GPU array and frees the memory associated
2500: with the old GPU array.
2502: The memory passed in CANNOT be freed by the user. It will be freed
2503: when the vector is destroyed.
2505: Not supported from Fortran
2507: Level: developer
2509: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray(), VecCUDAResetArray(), VecCUDAPlaceArray(), VecReplaceArray()
2511: @*/
2512: PetscErrorCode VecCUDAReplaceArray(Vec vin,const PetscScalar a[])
2513: {
2514: #if defined(PETSC_HAVE_CUDA)
2515: #endif
2518: #if defined(PETSC_HAVE_CUDA)
2519: if (((Vec_CUDA*)vin->spptr)->GPUarray_allocated) {
2520: cudaFree(((Vec_CUDA*)vin->spptr)->GPUarray_allocated);
2521: }
2522: ((Vec_CUDA*)vin->spptr)->GPUarray_allocated = ((Vec_CUDA*)vin->spptr)->GPUarray = (PetscScalar*)a;
2523: vin->offloadmask = PETSC_OFFLOAD_GPU;
2524: #endif
2525: PetscObjectStateIncrease((PetscObject)vin);
2526: return 0;
2527: }
2529: /*@C
2530: VecCUDAResetArray - Resets a vector to use its default memory. Call this
2531: after the use of VecCUDAPlaceArray().
2533: Not Collective
2535: Input Parameters:
2536: . vec - the vector
2538: Level: developer
2540: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray(), VecResetArray(), VecCUDAPlaceArray(), VecCUDAReplaceArray()
2542: @*/
2543: PetscErrorCode VecCUDAResetArray(Vec vin)
2544: {
2546: #if defined(PETSC_HAVE_CUDA)
2547: VecCUDACopyToGPU(vin);
2548: ((Vec_CUDA*)vin->spptr)->GPUarray = (PetscScalar *) ((Vec_Seq*)vin->data)->unplacedarray;
2549: ((Vec_Seq*)vin->data)->unplacedarray = 0;
2550: vin->offloadmask = PETSC_OFFLOAD_GPU;
2551: #endif
2552: PetscObjectStateIncrease((PetscObject)vin);
2553: return 0;
2554: }
2556: /*@C
2557: VecHIPGetArray - Provides access to the HIP buffer inside a vector.
2559: This function has semantics similar to VecGetArray(): the pointer
2560: returned by this function points to a consistent view of the vector
2561: data. This may involve a copy operation of data from the host to the
2562: device if the data on the device is out of date. If the device
2563: memory hasn't been allocated previously it will be allocated as part
2564: of this function call. VecHIPGetArray() assumes that
2565: the user will modify the vector data. This is similar to
2566: intent(inout) in fortran.
2568: The HIP device pointer has to be released by calling
2569: VecHIPRestoreArray(). Upon restoring the vector data
2570: the data on the host will be marked as out of date. A subsequent
2571: access of the host data will thus incur a data transfer from the
2572: device to the host.
2574: Input Parameter:
2575: . v - the vector
2577: Output Parameter:
2578: . a - the HIP device pointer
2580: Fortran note:
2581: This function is not currently available from Fortran.
2583: Level: intermediate
2585: .seealso: VecHIPRestoreArray(), VecHIPGetArrayRead(), VecHIPGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2586: @*/
2587: PETSC_EXTERN PetscErrorCode VecHIPGetArray(Vec v, PetscScalar **a)
2588: {
2590: #if defined(PETSC_HAVE_HIP)
2591: *a = 0;
2592: VecHIPCopyToGPU(v);
2593: *a = ((Vec_HIP*)v->spptr)->GPUarray;
2594: #endif
2595: return 0;
2596: }
2598: /*@C
2599: VecHIPRestoreArray - Restore a HIP device pointer previously acquired with VecHIPGetArray().
2601: This marks the host data as out of date. Subsequent access to the
2602: vector data on the host side with for instance VecGetArray() incurs a
2603: data transfer.
2605: Input Parameters:
2606: + v - the vector
2607: - a - the HIP device pointer. This pointer is invalid after
2608: VecHIPRestoreArray() returns.
2610: Fortran note:
2611: This function is not currently available from Fortran.
2613: Level: intermediate
2615: .seealso: VecHIPGetArray(), VecHIPGetArrayRead(), VecHIPGetArrayWrite(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2616: @*/
2617: PETSC_EXTERN PetscErrorCode VecHIPRestoreArray(Vec v, PetscScalar **a)
2618: {
2620: #if defined(PETSC_HAVE_HIP)
2621: v->offloadmask = PETSC_OFFLOAD_GPU;
2622: #endif
2624: PetscObjectStateIncrease((PetscObject)v);
2625: return 0;
2626: }
2628: /*@C
2629: VecHIPGetArrayRead - Provides read access to the HIP buffer inside a vector.
2631: This function is analogous to VecGetArrayRead(): The pointer
2632: returned by this function points to a consistent view of the vector
2633: data. This may involve a copy operation of data from the host to the
2634: device if the data on the device is out of date. If the device
2635: memory hasn't been allocated previously it will be allocated as part
2636: of this function call. VecHIPGetArrayRead() assumes that the
2637: user will not modify the vector data. This is analgogous to
2638: intent(in) in Fortran.
2640: The HIP device pointer has to be released by calling
2641: VecHIPRestoreArrayRead(). If the data on the host side was
2642: previously up to date it will remain so, i.e. data on both the device
2643: and the host is up to date. Accessing data on the host side does not
2644: incur a device to host data transfer.
2646: Input Parameter:
2647: . v - the vector
2649: Output Parameter:
2650: . a - the HIP pointer.
2652: Fortran note:
2653: This function is not currently available from Fortran.
2655: Level: intermediate
2657: .seealso: VecHIPRestoreArrayRead(), VecHIPGetArray(), VecHIPGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2658: @*/
2659: PETSC_EXTERN PetscErrorCode VecHIPGetArrayRead(Vec v, const PetscScalar **a)
2660: {
2662: #if defined(PETSC_HAVE_HIP)
2663: *a = 0;
2664: VecHIPCopyToGPU(v);
2665: *a = ((Vec_HIP*)v->spptr)->GPUarray;
2666: #endif
2667: return 0;
2668: }
2670: /*@C
2671: VecHIPRestoreArrayRead - Restore a HIP device pointer previously acquired with VecHIPGetArrayRead().
2673: If the data on the host side was previously up to date it will remain
2674: so, i.e. data on both the device and the host is up to date.
2675: Accessing data on the host side e.g. with VecGetArray() does not
2676: incur a device to host data transfer.
2678: Input Parameters:
2679: + v - the vector
2680: - a - the HIP device pointer. This pointer is invalid after
2681: VecHIPRestoreArrayRead() returns.
2683: Fortran note:
2684: This function is not currently available from Fortran.
2686: Level: intermediate
2688: .seealso: VecHIPGetArrayRead(), VecHIPGetArrayWrite(), VecHIPGetArray(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2689: @*/
2690: PETSC_EXTERN PetscErrorCode VecHIPRestoreArrayRead(Vec v, const PetscScalar **a)
2691: {
2693: *a = NULL;
2694: return 0;
2695: }
2697: /*@C
2698: VecHIPGetArrayWrite - Provides write access to the HIP buffer inside a vector.
2700: The data pointed to by the device pointer is uninitialized. The user
2701: may not read from this data. Furthermore, the entire array needs to
2702: be filled by the user to obtain well-defined behaviour. The device
2703: memory will be allocated by this function if it hasn't been allocated
2704: previously. This is analogous to intent(out) in Fortran.
2706: The device pointer needs to be released with
2707: VecHIPRestoreArrayWrite(). When the pointer is released the
2708: host data of the vector is marked as out of data. Subsequent access
2709: of the host data with e.g. VecGetArray() incurs a device to host data
2710: transfer.
2712: Input Parameter:
2713: . v - the vector
2715: Output Parameter:
2716: . a - the HIP pointer
2718: Fortran note:
2719: This function is not currently available from Fortran.
2721: Level: advanced
2723: .seealso: VecHIPRestoreArrayWrite(), VecHIPGetArray(), VecHIPGetArrayRead(), VecHIPGetArrayWrite(), VecGetArray(), VecGetArrayRead()
2724: @*/
2725: PETSC_EXTERN PetscErrorCode VecHIPGetArrayWrite(Vec v, PetscScalar **a)
2726: {
2728: #if defined(PETSC_HAVE_HIP)
2729: *a = 0;
2730: VecHIPAllocateCheck(v);
2731: *a = ((Vec_HIP*)v->spptr)->GPUarray;
2732: #endif
2733: return 0;
2734: }
2736: /*@C
2737: VecHIPRestoreArrayWrite - Restore a HIP device pointer previously acquired with VecHIPGetArrayWrite().
2739: Data on the host will be marked as out of date. Subsequent access of
2740: the data on the host side e.g. with VecGetArray() will incur a device
2741: to host data transfer.
2743: Input Parameters:
2744: + v - the vector
2745: - a - the HIP device pointer. This pointer is invalid after
2746: VecHIPRestoreArrayWrite() returns.
2748: Fortran note:
2749: This function is not currently available from Fortran.
2751: Level: intermediate
2753: .seealso: VecHIPGetArrayWrite(), VecHIPGetArray(), VecHIPGetArrayRead(), VecHIPGetArrayWrite(), VecGetArray(), VecRestoreArray(), VecGetArrayRead()
2754: @*/
2755: PETSC_EXTERN PetscErrorCode VecHIPRestoreArrayWrite(Vec v, PetscScalar **a)
2756: {
2758: #if defined(PETSC_HAVE_HIP)
2759: v->offloadmask = PETSC_OFFLOAD_GPU;
2760: #endif
2762: PetscObjectStateIncrease((PetscObject)v);
2763: return 0;
2764: }
2766: /*@C
2767: VecHIPPlaceArray - Allows one to replace the GPU array in a vector with a
2768: GPU array provided by the user. This is useful to avoid copying an
2769: array into a vector.
2771: Not Collective
2773: Input Parameters:
2774: + vec - the vector
2775: - array - the GPU array
2777: Notes:
2778: You can return to the original GPU array with a call to VecHIPResetArray()
2779: It is not possible to use VecHIPPlaceArray() and VecPlaceArray() at the
2780: same time on the same vector.
2782: Level: developer
2784: .seealso: VecPlaceArray(), VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray(), VecHIPResetArray(), VecHIPReplaceArray()
2786: @*/
2787: PetscErrorCode VecHIPPlaceArray(Vec vin,const PetscScalar a[])
2788: {
2790: #if defined(PETSC_HAVE_HIP)
2791: VecHIPCopyToGPU(vin);
2793: ((Vec_Seq*)vin->data)->unplacedarray = (PetscScalar *) ((Vec_HIP*)vin->spptr)->GPUarray; /* save previous GPU array so reset can bring it back */
2794: ((Vec_HIP*)vin->spptr)->GPUarray = (PetscScalar*)a;
2795: vin->offloadmask = PETSC_OFFLOAD_GPU;
2796: #endif
2797: PetscObjectStateIncrease((PetscObject)vin);
2798: return 0;
2799: }
2801: /*@C
2802: VecHIPReplaceArray - Allows one to replace the GPU array in a vector
2803: with a GPU array provided by the user. This is useful to avoid copying
2804: a GPU array into a vector.
2806: Not Collective
2808: Input Parameters:
2809: + vec - the vector
2810: - array - the GPU array
2812: Notes:
2813: This permanently replaces the GPU array and frees the memory associated
2814: with the old GPU array.
2816: The memory passed in CANNOT be freed by the user. It will be freed
2817: when the vector is destroyed.
2819: Not supported from Fortran
2821: Level: developer
2823: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray(), VecHIPResetArray(), VecHIPPlaceArray(), VecReplaceArray()
2825: @*/
2826: PetscErrorCode VecHIPReplaceArray(Vec vin,const PetscScalar a[])
2827: {
2829: #if defined(PETSC_HAVE_HIP)
2830: hipFree(((Vec_HIP*)vin->spptr)->GPUarray);
2831: ((Vec_HIP*)vin->spptr)->GPUarray = (PetscScalar*)a;
2832: vin->offloadmask = PETSC_OFFLOAD_GPU;
2833: #endif
2834: PetscObjectStateIncrease((PetscObject)vin);
2835: return 0;
2836: }
2838: /*@C
2839: VecHIPResetArray - Resets a vector to use its default memory. Call this
2840: after the use of VecHIPPlaceArray().
2842: Not Collective
2844: Input Parameters:
2845: . vec - the vector
2847: Level: developer
2849: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray(), VecResetArray(), VecHIPPlaceArray(), VecHIPReplaceArray()
2851: @*/
2852: PetscErrorCode VecHIPResetArray(Vec vin)
2853: {
2855: #if defined(PETSC_HAVE_HIP)
2856: VecHIPCopyToGPU(vin);
2857: ((Vec_HIP*)vin->spptr)->GPUarray = (PetscScalar *) ((Vec_Seq*)vin->data)->unplacedarray;
2858: ((Vec_Seq*)vin->data)->unplacedarray = 0;
2859: vin->offloadmask = PETSC_OFFLOAD_GPU;
2860: #endif
2861: PetscObjectStateIncrease((PetscObject)vin);
2862: return 0;
2863: }
2865: /*MC
2866: VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2867: and makes them accessible via a Fortran90 pointer.
2869: Synopsis:
2870: VecDuplicateVecsF90(Vec x,PetscInt n,{Vec, pointer :: y(:)},integer ierr)
2872: Collective on Vec
2874: Input Parameters:
2875: + x - a vector to mimic
2876: - n - the number of vectors to obtain
2878: Output Parameters:
2879: + y - Fortran90 pointer to the array of vectors
2880: - ierr - error code
2882: Example of Usage:
2883: .vb
2884: #include <petsc/finclude/petscvec.h>
2885: use petscvec
2887: Vec x
2888: Vec, pointer :: y(:)
2889: ....
2890: call VecDuplicateVecsF90(x,2,y,ierr)
2891: call VecSet(y(2),alpha,ierr)
2892: call VecSet(y(2),alpha,ierr)
2893: ....
2894: call VecDestroyVecsF90(2,y,ierr)
2895: .ve
2897: Notes:
2898: Not yet supported for all F90 compilers
2900: Use VecDestroyVecsF90() to free the space.
2902: Level: beginner
2904: .seealso: VecDestroyVecsF90(), VecDuplicateVecs()
2906: M*/
2908: /*MC
2909: VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2910: VecGetArrayF90().
2912: Synopsis:
2913: VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2915: Logically Collective on Vec
2917: Input Parameters:
2918: + x - vector
2919: - xx_v - the Fortran90 pointer to the array
2921: Output Parameter:
2922: . ierr - error code
2924: Example of Usage:
2925: .vb
2926: #include <petsc/finclude/petscvec.h>
2927: use petscvec
2929: PetscScalar, pointer :: xx_v(:)
2930: ....
2931: call VecGetArrayF90(x,xx_v,ierr)
2932: xx_v(3) = a
2933: call VecRestoreArrayF90(x,xx_v,ierr)
2934: .ve
2936: Level: beginner
2938: .seealso: VecGetArrayF90(), VecGetArray(), VecRestoreArray(), VecRestoreArrayReadF90()
2940: M*/
2942: /*MC
2943: VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().
2945: Synopsis:
2946: VecDestroyVecsF90(PetscInt n,{Vec, pointer :: x(:)},PetscErrorCode ierr)
2948: Collective on Vec
2950: Input Parameters:
2951: + n - the number of vectors previously obtained
2952: - x - pointer to array of vector pointers
2954: Output Parameter:
2955: . ierr - error code
2957: Notes:
2958: Not yet supported for all F90 compilers
2960: Level: beginner
2962: .seealso: VecDestroyVecs(), VecDuplicateVecsF90()
2964: M*/
2966: /*MC
2967: VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2968: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2969: this routine is implementation dependent. You MUST call VecRestoreArrayF90()
2970: when you no longer need access to the array.
2972: Synopsis:
2973: VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
2975: Logically Collective on Vec
2977: Input Parameter:
2978: . x - vector
2980: Output Parameters:
2981: + xx_v - the Fortran90 pointer to the array
2982: - ierr - error code
2984: Example of Usage:
2985: .vb
2986: #include <petsc/finclude/petscvec.h>
2987: use petscvec
2989: PetscScalar, pointer :: xx_v(:)
2990: ....
2991: call VecGetArrayF90(x,xx_v,ierr)
2992: xx_v(3) = a
2993: call VecRestoreArrayF90(x,xx_v,ierr)
2994: .ve
2996: If you ONLY intend to read entries from the array and not change any entries you should use VecGetArrayReadF90().
2998: Level: beginner
3000: .seealso: VecRestoreArrayF90(), VecGetArray(), VecRestoreArray(), VecGetArrayReadF90()
3002: M*/
3004: /*MC
3005: VecGetArrayReadF90 - Accesses a read only array from Fortran90. For default PETSc
3006: vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
3007: this routine is implementation dependent. You MUST call VecRestoreArrayReadF90()
3008: when you no longer need access to the array.
3010: Synopsis:
3011: VecGetArrayReadF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
3013: Logically Collective on Vec
3015: Input Parameter:
3016: . x - vector
3018: Output Parameters:
3019: + xx_v - the Fortran90 pointer to the array
3020: - ierr - error code
3022: Example of Usage:
3023: .vb
3024: #include <petsc/finclude/petscvec.h>
3025: use petscvec
3027: PetscScalar, pointer :: xx_v(:)
3028: ....
3029: call VecGetArrayReadF90(x,xx_v,ierr)
3030: a = xx_v(3)
3031: call VecRestoreArrayReadF90(x,xx_v,ierr)
3032: .ve
3034: If you intend to write entries into the array you must use VecGetArrayF90().
3036: Level: beginner
3038: .seealso: VecRestoreArrayReadF90(), VecGetArray(), VecRestoreArray(), VecGetArrayRead(), VecRestoreArrayRead(), VecGetArrayF90()
3040: M*/
3042: /*MC
3043: VecRestoreArrayReadF90 - Restores a readonly vector to a usable state after a call to
3044: VecGetArrayReadF90().
3046: Synopsis:
3047: VecRestoreArrayReadF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)
3049: Logically Collective on Vec
3051: Input Parameters:
3052: + x - vector
3053: - xx_v - the Fortran90 pointer to the array
3055: Output Parameter:
3056: . ierr - error code
3058: Example of Usage:
3059: .vb
3060: #include <petsc/finclude/petscvec.h>
3061: use petscvec
3063: PetscScalar, pointer :: xx_v(:)
3064: ....
3065: call VecGetArrayReadF90(x,xx_v,ierr)
3066: a = xx_v(3)
3067: call VecRestoreArrayReadF90(x,xx_v,ierr)
3068: .ve
3070: Level: beginner
3072: .seealso: VecGetArrayReadF90(), VecGetArray(), VecRestoreArray(), VecGetArrayRead(), VecRestoreArrayRead(), VecRestoreArrayF90()
3074: M*/
3076: /*@C
3077: VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
3078: processor's portion of the vector data. You MUST call VecRestoreArray2d()
3079: when you no longer need access to the array.
3081: Logically Collective
3083: Input Parameters:
3084: + x - the vector
3085: . m - first dimension of two dimensional array
3086: . n - second dimension of two dimensional array
3087: . mstart - first index you will use in first coordinate direction (often 0)
3088: - nstart - first index in the second coordinate direction (often 0)
3090: Output Parameter:
3091: . a - location to put pointer to the array
3093: Level: developer
3095: Notes:
3096: For a vector obtained from DMCreateLocalVector() mstart and nstart are likely
3097: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3098: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3099: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
3101: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3103: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3104: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3105: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3106: @*/
3107: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3108: {
3109: PetscInt i,N;
3110: PetscScalar *aa;
3115: VecGetLocalSize(x,&N);
3117: VecGetArray(x,&aa);
3119: PetscMalloc1(m,a);
3120: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3121: *a -= mstart;
3122: return 0;
3123: }
3125: /*@C
3126: VecGetArray2dWrite - Returns a pointer to a 2d contiguous array that will contain this
3127: processor's portion of the vector data. You MUST call VecRestoreArray2dWrite()
3128: when you no longer need access to the array.
3130: Logically Collective
3132: Input Parameters:
3133: + x - the vector
3134: . m - first dimension of two dimensional array
3135: . n - second dimension of two dimensional array
3136: . mstart - first index you will use in first coordinate direction (often 0)
3137: - nstart - first index in the second coordinate direction (often 0)
3139: Output Parameter:
3140: . a - location to put pointer to the array
3142: Level: developer
3144: Notes:
3145: For a vector obtained from DMCreateLocalVector() mstart and nstart are likely
3146: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3147: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3148: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
3150: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3152: Concepts: vector^accessing local values as 2d array
3154: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3155: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3156: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3157: @*/
3158: PetscErrorCode VecGetArray2dWrite(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3159: {
3160: PetscInt i,N;
3161: PetscScalar *aa;
3166: VecGetLocalSize(x,&N);
3168: VecGetArrayWrite(x,&aa);
3170: PetscMalloc1(m,a);
3171: for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3172: *a -= mstart;
3173: return 0;
3174: }
3176: /*@C
3177: VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.
3179: Logically Collective
3181: Input Parameters:
3182: + x - the vector
3183: . m - first dimension of two dimensional array
3184: . n - second dimension of the two dimensional array
3185: . mstart - first index you will use in first coordinate direction (often 0)
3186: . nstart - first index in the second coordinate direction (often 0)
3187: - a - location of pointer to array obtained from VecGetArray2d()
3189: Level: developer
3191: Notes:
3192: For regular PETSc vectors this routine does not involve any copies. For
3193: any special vectors that do not store local vector data in a contiguous
3194: array, this routine will copy the data back into the underlying
3195: vector data structure from the array obtained with VecGetArray().
3197: This routine actually zeros out the a pointer.
3199: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3200: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3201: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3202: @*/
3203: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3204: {
3205: void *dummy;
3210: dummy = (void*)(*a + mstart);
3211: PetscFree(dummy);
3212: VecRestoreArray(x,NULL);
3213: return 0;
3214: }
3216: /*@C
3217: VecRestoreArray2dWrite - Restores a vector after VecGetArray2dWrite() has been called.
3219: Logically Collective
3221: Input Parameters:
3222: + x - the vector
3223: . m - first dimension of two dimensional array
3224: . n - second dimension of the two dimensional array
3225: . mstart - first index you will use in first coordinate direction (often 0)
3226: . nstart - first index in the second coordinate direction (often 0)
3227: - a - location of pointer to array obtained from VecGetArray2d()
3229: Level: developer
3231: Notes:
3232: For regular PETSc vectors this routine does not involve any copies. For
3233: any special vectors that do not store local vector data in a contiguous
3234: array, this routine will copy the data back into the underlying
3235: vector data structure from the array obtained with VecGetArray().
3237: This routine actually zeros out the a pointer.
3239: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3240: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3241: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3242: @*/
3243: PetscErrorCode VecRestoreArray2dWrite(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3244: {
3245: void *dummy;
3250: dummy = (void*)(*a + mstart);
3251: PetscFree(dummy);
3252: VecRestoreArrayWrite(x,NULL);
3253: return 0;
3254: }
3256: /*@C
3257: VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
3258: processor's portion of the vector data. You MUST call VecRestoreArray1d()
3259: when you no longer need access to the array.
3261: Logically Collective
3263: Input Parameters:
3264: + x - the vector
3265: . m - first dimension of two dimensional array
3266: - mstart - first index you will use in first coordinate direction (often 0)
3268: Output Parameter:
3269: . a - location to put pointer to the array
3271: Level: developer
3273: Notes:
3274: For a vector obtained from DMCreateLocalVector() mstart are likely
3275: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3276: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners().
3278: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3280: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3281: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3282: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3283: @*/
3284: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3285: {
3286: PetscInt N;
3291: VecGetLocalSize(x,&N);
3293: VecGetArray(x,a);
3294: *a -= mstart;
3295: return 0;
3296: }
3298: /*@C
3299: VecGetArray1dWrite - Returns a pointer to a 1d contiguous array that will contain this
3300: processor's portion of the vector data. You MUST call VecRestoreArray1dWrite()
3301: when you no longer need access to the array.
3303: Logically Collective
3305: Input Parameters:
3306: + x - the vector
3307: . m - first dimension of two dimensional array
3308: - mstart - first index you will use in first coordinate direction (often 0)
3310: Output Parameter:
3311: . a - location to put pointer to the array
3313: Level: developer
3315: Notes:
3316: For a vector obtained from DMCreateLocalVector() mstart are likely
3317: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3318: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners().
3320: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3322: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3323: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3324: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3325: @*/
3326: PetscErrorCode VecGetArray1dWrite(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3327: {
3328: PetscInt N;
3333: VecGetLocalSize(x,&N);
3335: VecGetArrayWrite(x,a);
3336: *a -= mstart;
3337: return 0;
3338: }
3340: /*@C
3341: VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.
3343: Logically Collective
3345: Input Parameters:
3346: + x - the vector
3347: . m - first dimension of two dimensional array
3348: . mstart - first index you will use in first coordinate direction (often 0)
3349: - a - location of pointer to array obtained from VecGetArray21()
3351: Level: developer
3353: Notes:
3354: For regular PETSc vectors this routine does not involve any copies. For
3355: any special vectors that do not store local vector data in a contiguous
3356: array, this routine will copy the data back into the underlying
3357: vector data structure from the array obtained with VecGetArray1d().
3359: This routine actually zeros out the a pointer.
3361: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3362: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3363: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3364: @*/
3365: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3366: {
3369: VecRestoreArray(x,NULL);
3370: return 0;
3371: }
3373: /*@C
3374: VecRestoreArray1dWrite - Restores a vector after VecGetArray1dWrite() has been called.
3376: Logically Collective
3378: Input Parameters:
3379: + x - the vector
3380: . m - first dimension of two dimensional array
3381: . mstart - first index you will use in first coordinate direction (often 0)
3382: - a - location of pointer to array obtained from VecGetArray21()
3384: Level: developer
3386: Notes:
3387: For regular PETSc vectors this routine does not involve any copies. For
3388: any special vectors that do not store local vector data in a contiguous
3389: array, this routine will copy the data back into the underlying
3390: vector data structure from the array obtained with VecGetArray1d().
3392: This routine actually zeros out the a pointer.
3394: Concepts: vector^accessing local values as 1d array
3396: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3397: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3398: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3399: @*/
3400: PetscErrorCode VecRestoreArray1dWrite(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3401: {
3404: VecRestoreArrayWrite(x,NULL);
3405: return 0;
3406: }
3408: /*@C
3409: VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
3410: processor's portion of the vector data. You MUST call VecRestoreArray3d()
3411: when you no longer need access to the array.
3413: Logically Collective
3415: Input Parameters:
3416: + x - the vector
3417: . m - first dimension of three dimensional array
3418: . n - second dimension of three dimensional array
3419: . p - third dimension of three dimensional array
3420: . mstart - first index you will use in first coordinate direction (often 0)
3421: . nstart - first index in the second coordinate direction (often 0)
3422: - pstart - first index in the third coordinate direction (often 0)
3424: Output Parameter:
3425: . a - location to put pointer to the array
3427: Level: developer
3429: Notes:
3430: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
3431: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3432: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3433: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
3435: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3437: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3438: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3439: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3440: @*/
3441: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3442: {
3443: PetscInt i,N,j;
3444: PetscScalar *aa,**b;
3449: VecGetLocalSize(x,&N);
3451: VecGetArray(x,&aa);
3453: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3454: b = (PetscScalar**)((*a) + m);
3455: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3456: for (i=0; i<m; i++)
3457: for (j=0; j<n; j++)
3458: b[i*n+j] = aa + i*n*p + j*p - pstart;
3459: *a -= mstart;
3460: return 0;
3461: }
3463: /*@C
3464: VecGetArray3dWrite - Returns a pointer to a 3d contiguous array that will contain this
3465: processor's portion of the vector data. You MUST call VecRestoreArray3dWrite()
3466: when you no longer need access to the array.
3468: Logically Collective
3470: Input Parameters:
3471: + x - the vector
3472: . m - first dimension of three dimensional array
3473: . n - second dimension of three dimensional array
3474: . p - third dimension of three dimensional array
3475: . mstart - first index you will use in first coordinate direction (often 0)
3476: . nstart - first index in the second coordinate direction (often 0)
3477: - pstart - first index in the third coordinate direction (often 0)
3479: Output Parameter:
3480: . a - location to put pointer to the array
3482: Level: developer
3484: Notes:
3485: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
3486: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3487: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3488: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
3490: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3492: Concepts: vector^accessing local values as 3d array
3494: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3495: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3496: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3497: @*/
3498: PetscErrorCode VecGetArray3dWrite(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3499: {
3500: PetscInt i,N,j;
3501: PetscScalar *aa,**b;
3506: VecGetLocalSize(x,&N);
3508: VecGetArrayWrite(x,&aa);
3510: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3511: b = (PetscScalar**)((*a) + m);
3512: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3513: for (i=0; i<m; i++)
3514: for (j=0; j<n; j++)
3515: b[i*n+j] = aa + i*n*p + j*p - pstart;
3517: *a -= mstart;
3518: return 0;
3519: }
3521: /*@C
3522: VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.
3524: Logically Collective
3526: Input Parameters:
3527: + x - the vector
3528: . m - first dimension of three dimensional array
3529: . n - second dimension of the three dimensional array
3530: . p - third dimension of the three dimensional array
3531: . mstart - first index you will use in first coordinate direction (often 0)
3532: . nstart - first index in the second coordinate direction (often 0)
3533: . pstart - first index in the third coordinate direction (often 0)
3534: - a - location of pointer to array obtained from VecGetArray3d()
3536: Level: developer
3538: Notes:
3539: For regular PETSc vectors this routine does not involve any copies. For
3540: any special vectors that do not store local vector data in a contiguous
3541: array, this routine will copy the data back into the underlying
3542: vector data structure from the array obtained with VecGetArray().
3544: This routine actually zeros out the a pointer.
3546: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3547: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3548: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3549: @*/
3550: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3551: {
3552: void *dummy;
3557: dummy = (void*)(*a + mstart);
3558: PetscFree(dummy);
3559: VecRestoreArray(x,NULL);
3560: return 0;
3561: }
3563: /*@C
3564: VecRestoreArray3dWrite - Restores a vector after VecGetArray3dWrite() has been called.
3566: Logically Collective
3568: Input Parameters:
3569: + x - the vector
3570: . m - first dimension of three dimensional array
3571: . n - second dimension of the three dimensional array
3572: . p - third dimension of the three dimensional array
3573: . mstart - first index you will use in first coordinate direction (often 0)
3574: . nstart - first index in the second coordinate direction (often 0)
3575: . pstart - first index in the third coordinate direction (often 0)
3576: - a - location of pointer to array obtained from VecGetArray3d()
3578: Level: developer
3580: Notes:
3581: For regular PETSc vectors this routine does not involve any copies. For
3582: any special vectors that do not store local vector data in a contiguous
3583: array, this routine will copy the data back into the underlying
3584: vector data structure from the array obtained with VecGetArray().
3586: This routine actually zeros out the a pointer.
3588: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3589: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3590: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3591: @*/
3592: PetscErrorCode VecRestoreArray3dWrite(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3593: {
3594: void *dummy;
3599: dummy = (void*)(*a + mstart);
3600: PetscFree(dummy);
3601: VecRestoreArrayWrite(x,NULL);
3602: return 0;
3603: }
3605: /*@C
3606: VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
3607: processor's portion of the vector data. You MUST call VecRestoreArray4d()
3608: when you no longer need access to the array.
3610: Logically Collective
3612: Input Parameters:
3613: + x - the vector
3614: . m - first dimension of four dimensional array
3615: . n - second dimension of four dimensional array
3616: . p - third dimension of four dimensional array
3617: . q - fourth dimension of four dimensional array
3618: . mstart - first index you will use in first coordinate direction (often 0)
3619: . nstart - first index in the second coordinate direction (often 0)
3620: . pstart - first index in the third coordinate direction (often 0)
3621: - qstart - first index in the fourth coordinate direction (often 0)
3623: Output Parameter:
3624: . a - location to put pointer to the array
3626: Level: beginner
3628: Notes:
3629: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
3630: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3631: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3632: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
3634: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3636: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3637: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3638: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3639: @*/
3640: PetscErrorCode VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3641: {
3642: PetscInt i,N,j,k;
3643: PetscScalar *aa,***b,**c;
3648: VecGetLocalSize(x,&N);
3650: VecGetArray(x,&aa);
3652: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
3653: b = (PetscScalar***)((*a) + m);
3654: c = (PetscScalar**)(b + m*n);
3655: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3656: for (i=0; i<m; i++)
3657: for (j=0; j<n; j++)
3658: b[i*n+j] = c + i*n*p + j*p - pstart;
3659: for (i=0; i<m; i++)
3660: for (j=0; j<n; j++)
3661: for (k=0; k<p; k++)
3662: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
3663: *a -= mstart;
3664: return 0;
3665: }
3667: /*@C
3668: VecGetArray4dWrite - Returns a pointer to a 4d contiguous array that will contain this
3669: processor's portion of the vector data. You MUST call VecRestoreArray4dWrite()
3670: when you no longer need access to the array.
3672: Logically Collective
3674: Input Parameters:
3675: + x - the vector
3676: . m - first dimension of four dimensional array
3677: . n - second dimension of four dimensional array
3678: . p - third dimension of four dimensional array
3679: . q - fourth dimension of four dimensional array
3680: . mstart - first index you will use in first coordinate direction (often 0)
3681: . nstart - first index in the second coordinate direction (often 0)
3682: . pstart - first index in the third coordinate direction (often 0)
3683: - qstart - first index in the fourth coordinate direction (often 0)
3685: Output Parameter:
3686: . a - location to put pointer to the array
3688: Level: beginner
3690: Notes:
3691: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
3692: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3693: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3694: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
3696: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3698: Concepts: vector^accessing local values as 3d array
3700: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3701: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3702: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3703: @*/
3704: PetscErrorCode VecGetArray4dWrite(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3705: {
3706: PetscInt i,N,j,k;
3707: PetscScalar *aa,***b,**c;
3712: VecGetLocalSize(x,&N);
3714: VecGetArrayWrite(x,&aa);
3716: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
3717: b = (PetscScalar***)((*a) + m);
3718: c = (PetscScalar**)(b + m*n);
3719: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
3720: for (i=0; i<m; i++)
3721: for (j=0; j<n; j++)
3722: b[i*n+j] = c + i*n*p + j*p - pstart;
3723: for (i=0; i<m; i++)
3724: for (j=0; j<n; j++)
3725: for (k=0; k<p; k++)
3726: c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
3727: *a -= mstart;
3728: return 0;
3729: }
3731: /*@C
3732: VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.
3734: Logically Collective
3736: Input Parameters:
3737: + x - the vector
3738: . m - first dimension of four dimensional array
3739: . n - second dimension of the four dimensional array
3740: . p - third dimension of the four dimensional array
3741: . q - fourth dimension of the four dimensional array
3742: . mstart - first index you will use in first coordinate direction (often 0)
3743: . nstart - first index in the second coordinate direction (often 0)
3744: . pstart - first index in the third coordinate direction (often 0)
3745: . qstart - first index in the fourth coordinate direction (often 0)
3746: - a - location of pointer to array obtained from VecGetArray4d()
3748: Level: beginner
3750: Notes:
3751: For regular PETSc vectors this routine does not involve any copies. For
3752: any special vectors that do not store local vector data in a contiguous
3753: array, this routine will copy the data back into the underlying
3754: vector data structure from the array obtained with VecGetArray().
3756: This routine actually zeros out the a pointer.
3758: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3759: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3760: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3761: @*/
3762: PetscErrorCode VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3763: {
3764: void *dummy;
3769: dummy = (void*)(*a + mstart);
3770: PetscFree(dummy);
3771: VecRestoreArray(x,NULL);
3772: return 0;
3773: }
3775: /*@C
3776: VecRestoreArray4dWrite - Restores a vector after VecGetArray3dWrite() has been called.
3778: Logically Collective
3780: Input Parameters:
3781: + x - the vector
3782: . m - first dimension of four dimensional array
3783: . n - second dimension of the four dimensional array
3784: . p - third dimension of the four dimensional array
3785: . q - fourth dimension of the four dimensional array
3786: . mstart - first index you will use in first coordinate direction (often 0)
3787: . nstart - first index in the second coordinate direction (often 0)
3788: . pstart - first index in the third coordinate direction (often 0)
3789: . qstart - first index in the fourth coordinate direction (often 0)
3790: - a - location of pointer to array obtained from VecGetArray4d()
3792: Level: beginner
3794: Notes:
3795: For regular PETSc vectors this routine does not involve any copies. For
3796: any special vectors that do not store local vector data in a contiguous
3797: array, this routine will copy the data back into the underlying
3798: vector data structure from the array obtained with VecGetArray().
3800: This routine actually zeros out the a pointer.
3802: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3803: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3804: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3805: @*/
3806: PetscErrorCode VecRestoreArray4dWrite(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3807: {
3808: void *dummy;
3813: dummy = (void*)(*a + mstart);
3814: PetscFree(dummy);
3815: VecRestoreArrayWrite(x,NULL);
3816: return 0;
3817: }
3819: /*@C
3820: VecGetArray2dRead - Returns a pointer to a 2d contiguous array that contains this
3821: processor's portion of the vector data. You MUST call VecRestoreArray2dRead()
3822: when you no longer need access to the array.
3824: Logically Collective
3826: Input Parameters:
3827: + x - the vector
3828: . m - first dimension of two dimensional array
3829: . n - second dimension of two dimensional array
3830: . mstart - first index you will use in first coordinate direction (often 0)
3831: - nstart - first index in the second coordinate direction (often 0)
3833: Output Parameter:
3834: . a - location to put pointer to the array
3836: Level: developer
3838: Notes:
3839: For a vector obtained from DMCreateLocalVector() mstart and nstart are likely
3840: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3841: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
3842: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
3844: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3846: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3847: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3848: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3849: @*/
3850: PetscErrorCode VecGetArray2dRead(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3851: {
3852: PetscInt i,N;
3853: const PetscScalar *aa;
3858: VecGetLocalSize(x,&N);
3860: VecGetArrayRead(x,&aa);
3862: PetscMalloc1(m,a);
3863: for (i=0; i<m; i++) (*a)[i] = (PetscScalar*) aa + i*n - nstart;
3864: *a -= mstart;
3865: return 0;
3866: }
3868: /*@C
3869: VecRestoreArray2dRead - Restores a vector after VecGetArray2dRead() has been called.
3871: Logically Collective
3873: Input Parameters:
3874: + x - the vector
3875: . m - first dimension of two dimensional array
3876: . n - second dimension of the two dimensional array
3877: . mstart - first index you will use in first coordinate direction (often 0)
3878: . nstart - first index in the second coordinate direction (often 0)
3879: - a - location of pointer to array obtained from VecGetArray2d()
3881: Level: developer
3883: Notes:
3884: For regular PETSc vectors this routine does not involve any copies. For
3885: any special vectors that do not store local vector data in a contiguous
3886: array, this routine will copy the data back into the underlying
3887: vector data structure from the array obtained with VecGetArray().
3889: This routine actually zeros out the a pointer.
3891: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3892: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3893: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3894: @*/
3895: PetscErrorCode VecRestoreArray2dRead(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3896: {
3897: void *dummy;
3902: dummy = (void*)(*a + mstart);
3903: PetscFree(dummy);
3904: VecRestoreArrayRead(x,NULL);
3905: return 0;
3906: }
3908: /*@C
3909: VecGetArray1dRead - Returns a pointer to a 1d contiguous array that contains this
3910: processor's portion of the vector data. You MUST call VecRestoreArray1dRead()
3911: when you no longer need access to the array.
3913: Logically Collective
3915: Input Parameters:
3916: + x - the vector
3917: . m - first dimension of two dimensional array
3918: - mstart - first index you will use in first coordinate direction (often 0)
3920: Output Parameter:
3921: . a - location to put pointer to the array
3923: Level: developer
3925: Notes:
3926: For a vector obtained from DMCreateLocalVector() mstart are likely
3927: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
3928: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners().
3930: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
3932: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3933: VecRestoreArray2d(), DMDAVecGetArray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3934: VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3935: @*/
3936: PetscErrorCode VecGetArray1dRead(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3937: {
3938: PetscInt N;
3943: VecGetLocalSize(x,&N);
3945: VecGetArrayRead(x,(const PetscScalar**)a);
3946: *a -= mstart;
3947: return 0;
3948: }
3950: /*@C
3951: VecRestoreArray1dRead - Restores a vector after VecGetArray1dRead() has been called.
3953: Logically Collective
3955: Input Parameters:
3956: + x - the vector
3957: . m - first dimension of two dimensional array
3958: . mstart - first index you will use in first coordinate direction (often 0)
3959: - a - location of pointer to array obtained from VecGetArray21()
3961: Level: developer
3963: Notes:
3964: For regular PETSc vectors this routine does not involve any copies. For
3965: any special vectors that do not store local vector data in a contiguous
3966: array, this routine will copy the data back into the underlying
3967: vector data structure from the array obtained with VecGetArray1dRead().
3969: This routine actually zeros out the a pointer.
3971: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3972: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
3973: VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3974: @*/
3975: PetscErrorCode VecRestoreArray1dRead(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3976: {
3979: VecRestoreArrayRead(x,NULL);
3980: return 0;
3981: }
3983: /*@C
3984: VecGetArray3dRead - Returns a pointer to a 3d contiguous array that contains this
3985: processor's portion of the vector data. You MUST call VecRestoreArray3dRead()
3986: when you no longer need access to the array.
3988: Logically Collective
3990: Input Parameters:
3991: + x - the vector
3992: . m - first dimension of three dimensional array
3993: . n - second dimension of three dimensional array
3994: . p - third dimension of three dimensional array
3995: . mstart - first index you will use in first coordinate direction (often 0)
3996: . nstart - first index in the second coordinate direction (often 0)
3997: - pstart - first index in the third coordinate direction (often 0)
3999: Output Parameter:
4000: . a - location to put pointer to the array
4002: Level: developer
4004: Notes:
4005: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
4006: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
4007: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
4008: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3dRead().
4010: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
4012: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
4013: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
4014: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
4015: @*/
4016: PetscErrorCode VecGetArray3dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
4017: {
4018: PetscInt i,N,j;
4019: const PetscScalar *aa;
4020: PetscScalar **b;
4025: VecGetLocalSize(x,&N);
4027: VecGetArrayRead(x,&aa);
4029: PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
4030: b = (PetscScalar**)((*a) + m);
4031: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
4032: for (i=0; i<m; i++)
4033: for (j=0; j<n; j++)
4034: b[i*n+j] = (PetscScalar *)aa + i*n*p + j*p - pstart;
4035: *a -= mstart;
4036: return 0;
4037: }
4039: /*@C
4040: VecRestoreArray3dRead - Restores a vector after VecGetArray3dRead() has been called.
4042: Logically Collective
4044: Input Parameters:
4045: + x - the vector
4046: . m - first dimension of three dimensional array
4047: . n - second dimension of the three dimensional array
4048: . p - third dimension of the three dimensional array
4049: . mstart - first index you will use in first coordinate direction (often 0)
4050: . nstart - first index in the second coordinate direction (often 0)
4051: . pstart - first index in the third coordinate direction (often 0)
4052: - a - location of pointer to array obtained from VecGetArray3dRead()
4054: Level: developer
4056: Notes:
4057: For regular PETSc vectors this routine does not involve any copies. For
4058: any special vectors that do not store local vector data in a contiguous
4059: array, this routine will copy the data back into the underlying
4060: vector data structure from the array obtained with VecGetArray().
4062: This routine actually zeros out the a pointer.
4064: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
4065: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
4066: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
4067: @*/
4068: PetscErrorCode VecRestoreArray3dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
4069: {
4070: void *dummy;
4075: dummy = (void*)(*a + mstart);
4076: PetscFree(dummy);
4077: VecRestoreArrayRead(x,NULL);
4078: return 0;
4079: }
4081: /*@C
4082: VecGetArray4dRead - Returns a pointer to a 4d contiguous array that contains this
4083: processor's portion of the vector data. You MUST call VecRestoreArray4dRead()
4084: when you no longer need access to the array.
4086: Logically Collective
4088: Input Parameters:
4089: + x - the vector
4090: . m - first dimension of four dimensional array
4091: . n - second dimension of four dimensional array
4092: . p - third dimension of four dimensional array
4093: . q - fourth dimension of four dimensional array
4094: . mstart - first index you will use in first coordinate direction (often 0)
4095: . nstart - first index in the second coordinate direction (often 0)
4096: . pstart - first index in the third coordinate direction (often 0)
4097: - qstart - first index in the fourth coordinate direction (often 0)
4099: Output Parameter:
4100: . a - location to put pointer to the array
4102: Level: beginner
4104: Notes:
4105: For a vector obtained from DMCreateLocalVector() mstart, nstart, and pstart are likely
4106: obtained from the corner indices obtained from DMDAGetGhostCorners() while for
4107: DMCreateGlobalVector() they are the corner indices from DMDAGetCorners(). In both cases
4108: the arguments from DMDAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
4110: For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.
4112: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
4113: VecRestoreArray2d(), DMDAVecGetarray(), DMDAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
4114: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
4115: @*/
4116: PetscErrorCode VecGetArray4dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
4117: {
4118: PetscInt i,N,j,k;
4119: const PetscScalar *aa;
4120: PetscScalar ***b,**c;
4125: VecGetLocalSize(x,&N);
4127: VecGetArrayRead(x,&aa);
4129: PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
4130: b = (PetscScalar***)((*a) + m);
4131: c = (PetscScalar**)(b + m*n);
4132: for (i=0; i<m; i++) (*a)[i] = b + i*n - nstart;
4133: for (i=0; i<m; i++)
4134: for (j=0; j<n; j++)
4135: b[i*n+j] = c + i*n*p + j*p - pstart;
4136: for (i=0; i<m; i++)
4137: for (j=0; j<n; j++)
4138: for (k=0; k<p; k++)
4139: c[i*n*p+j*p+k] = (PetscScalar*) aa + i*n*p*q + j*p*q + k*q - qstart;
4140: *a -= mstart;
4141: return 0;
4142: }
4144: /*@C
4145: VecRestoreArray4dRead - Restores a vector after VecGetArray3d() has been called.
4147: Logically Collective
4149: Input Parameters:
4150: + x - the vector
4151: . m - first dimension of four dimensional array
4152: . n - second dimension of the four dimensional array
4153: . p - third dimension of the four dimensional array
4154: . q - fourth dimension of the four dimensional array
4155: . mstart - first index you will use in first coordinate direction (often 0)
4156: . nstart - first index in the second coordinate direction (often 0)
4157: . pstart - first index in the third coordinate direction (often 0)
4158: . qstart - first index in the fourth coordinate direction (often 0)
4159: - a - location of pointer to array obtained from VecGetArray4dRead()
4161: Level: beginner
4163: Notes:
4164: For regular PETSc vectors this routine does not involve any copies. For
4165: any special vectors that do not store local vector data in a contiguous
4166: array, this routine will copy the data back into the underlying
4167: vector data structure from the array obtained with VecGetArray().
4169: This routine actually zeros out the a pointer.
4171: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
4172: VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DMDAVecGetArray(), DMDAVecRestoreArray()
4173: VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
4174: @*/
4175: PetscErrorCode VecRestoreArray4dRead(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
4176: {
4177: void *dummy;
4182: dummy = (void*)(*a + mstart);
4183: PetscFree(dummy);
4184: VecRestoreArrayRead(x,NULL);
4185: return 0;
4186: }
4188: #if defined(PETSC_USE_DEBUG)
4190: /*@
4191: VecLockGet - Gets the current lock status of a vector
4193: Logically Collective on Vec
4195: Input Parameter:
4196: . x - the vector
4198: Output Parameter:
4199: . state - greater than zero indicates the vector is locked for read; less then zero indicates the vector is
4200: locked for write; equal to zero means the vector is unlocked, that is, it is free to read or write.
4202: Level: beginner
4204: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockReadPush(), VecLockReadPop()
4205: @*/
4206: PetscErrorCode VecLockGet(Vec x,PetscInt *state)
4207: {
4209: *state = x->lock;
4210: return 0;
4211: }
4213: /*@
4214: VecLockReadPush - Pushes a read-only lock on a vector to prevent it from writing
4216: Logically Collective on Vec
4218: Input Parameter:
4219: . x - the vector
4221: Notes:
4222: If this is set then calls to VecGetArray() or VecSetValues() or any other routines that change the vectors values will fail.
4224: The call can be nested, i.e., called multiple times on the same vector, but each VecLockReadPush(x) has to have one matching
4225: VecLockReadPop(x), which removes the latest read-only lock.
4227: Level: beginner
4229: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockReadPop(), VecLockGet()
4230: @*/
4231: PetscErrorCode VecLockReadPush(Vec x)
4232: {
4235: x->lock++;
4236: return 0;
4237: }
4239: /*@
4240: VecLockReadPop - Pops a read-only lock from a vector
4242: Logically Collective on Vec
4244: Input Parameter:
4245: . x - the vector
4247: Level: beginner
4249: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockReadPush(), VecLockGet()
4250: @*/
4251: PetscErrorCode VecLockReadPop(Vec x)
4252: {
4254: x->lock--;
4256: return 0;
4257: }
4259: /*@C
4260: VecLockWriteSet_Private - Lock or unlock a vector for exclusive read/write access
4262: Logically Collective on Vec
4264: Input Parameters:
4265: + x - the vector
4266: - flg - PETSC_TRUE to lock the vector for writing; PETSC_FALSE to unlock it.
4268: Notes:
4269: The function is usefull in split-phase computations, which usually have a begin phase and an end phase.
4270: One can call VecLockWriteSet_Private(x,PETSC_TRUE) in the begin phase to lock a vector for exclusive
4271: access, and call VecLockWriteSet_Private(x,PETSC_FALSE) in the end phase to unlock the vector from exclusive
4272: access. In this way, one is ensured no other operations can access the vector in between. The code may like
4274: VecGetArray(x,&xdata); // begin phase
4275: VecLockWriteSet_Private(v,PETSC_TRUE);
4277: Other operations, which can not acceess x anymore (they can access xdata, of course)
4279: VecRestoreArray(x,&vdata); // end phase
4280: VecLockWriteSet_Private(v,PETSC_FALSE);
4282: The call can not be nested on the same vector, in other words, one can not call VecLockWriteSet_Private(x,PETSC_TRUE)
4283: again before calling VecLockWriteSet_Private(v,PETSC_FALSE).
4285: Level: beginner
4287: .seealso: VecRestoreArray(), VecGetArrayRead(), VecLockReadPush(), VecLockReadPop(), VecLockGet()
4288: @*/
4289: PetscErrorCode VecLockWriteSet_Private(Vec x,PetscBool flg)
4290: {
4292: if (flg) {
4295: else x->lock = -1;
4296: } else {
4298: x->lock = 0;
4299: }
4300: return 0;
4301: }
4303: /*@
4304: VecLockPush - Pushes a read-only lock on a vector to prevent it from writing
4306: Level: deprecated
4308: .seealso: VecLockReadPush()
4309: @*/
4310: PetscErrorCode VecLockPush(Vec x)
4311: {
4312: VecLockReadPush(x);
4313: return 0;
4314: }
4316: /*@
4317: VecLockPop - Pops a read-only lock from a vector
4319: Level: deprecated
4321: .seealso: VecLockReadPop()
4322: @*/
4323: PetscErrorCode VecLockPop(Vec x)
4324: {
4325: VecLockReadPop(x);
4326: return 0;
4327: }
4329: #endif