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/vecimpl.h>

  7: PetscInt VecGetSubVectorSavedStateId = -1;

  9: #if PetscDefined(USE_DEBUG)
 10: // this is a no-op '0' macro in optimized builds
 11: PetscErrorCode VecValidValues_Internal(Vec vec, PetscInt argnum, PetscBool begin)
 12: {
 13:   PetscFunctionBegin;
 14:   if (vec->petscnative || vec->ops->getarray) {
 15:     PetscInt           n;
 16:     const PetscScalar *x;
 17:     PetscOffloadMask   mask;

 19:     PetscCall(VecGetOffloadMask(vec, &mask));
 20:     if (!PetscOffloadHost(mask)) PetscFunctionReturn(PETSC_SUCCESS);
 21:     PetscCall(VecGetLocalSize(vec, &n));
 22:     PetscCall(VecGetArrayRead(vec, &x));
 23:     for (PetscInt i = 0; i < n; i++) {
 24:       if (begin) {
 25:         PetscCheck(!PetscIsInfOrNanScalar(x[i]), PETSC_COMM_SELF, PETSC_ERR_FP, "Vec entry at local location %" PetscInt_FMT " is not-a-number or infinite at beginning of function: Parameter number %" PetscInt_FMT, i, argnum);
 26:       } else {
 27:         PetscCheck(!PetscIsInfOrNanScalar(x[i]), PETSC_COMM_SELF, PETSC_ERR_FP, "Vec entry at local location %" PetscInt_FMT " is not-a-number or infinite at end of function: Parameter number %" PetscInt_FMT, i, argnum);
 28:       }
 29:     }
 30:     PetscCall(VecRestoreArrayRead(vec, &x));
 31:   }
 32:   PetscFunctionReturn(PETSC_SUCCESS);
 33: }
 34: #endif

 36: /*@
 37:   VecMaxPointwiseDivide - Computes the maximum of the componentwise division `max = max_i abs(x[i]/y[i])`.

 39:   Logically Collective

 41:   Input Parameters:
 42: + x - the numerators
 43: - y - the denominators

 45:   Output Parameter:
 46: . max - the result

 48:   Level: advanced

 50:   Notes:
 51:   `x` and `y` may be the same vector

 53:   if a particular `y[i]` is zero, it is treated as 1 in the above formula

 55: .seealso: [](ch_vectors), `Vec`, `VecPointwiseDivide()`, `VecPointwiseMult()`, `VecPointwiseMax()`, `VecPointwiseMin()`, `VecPointwiseMaxAbs()`
 56: @*/
 57: PetscErrorCode VecMaxPointwiseDivide(Vec x, Vec y, PetscReal *max)
 58: {
 59:   PetscFunctionBegin;
 62:   PetscAssertPointer(max, 3);
 65:   PetscCheckSameTypeAndComm(x, 1, y, 2);
 66:   VecCheckSameSize(x, 1, y, 2);
 67:   VecCheckAssembled(x);
 68:   VecCheckAssembled(y);
 69:   PetscCall(VecLockReadPush(x));
 70:   PetscCall(VecLockReadPush(y));
 71:   PetscUseTypeMethod(x, maxpointwisedivide, y, max);
 72:   PetscCall(VecLockReadPop(x));
 73:   PetscCall(VecLockReadPop(y));
 74:   PetscFunctionReturn(PETSC_SUCCESS);
 75: }

 77: /*@
 78:   VecDot - Computes the vector dot product.

 80:   Collective

 82:   Input Parameters:
 83: + x - first vector
 84: - y - second vector

 86:   Output Parameter:
 87: . val - the dot product

 89:   Level: intermediate

 91:   Notes for Users of Complex Numbers:
 92:   For complex vectors, `VecDot()` computes
 93: .vb
 94:   val = (x,y) = y^H x,
 95: .ve
 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: .vb
102:   val = (x,y) = y^T x,
103: .ve
104:   where y^T denotes the transpose of y.

106: .seealso: [](ch_vectors), `Vec`, `VecMDot()`, `VecTDot()`, `VecNorm()`, `VecDotBegin()`, `VecDotEnd()`, `VecDotRealPart()`
107: @*/
108: PetscErrorCode VecDot(Vec x, Vec y, PetscScalar *val)
109: {
110:   PetscFunctionBegin;
113:   PetscAssertPointer(val, 3);
116:   PetscCheckSameTypeAndComm(x, 1, y, 2);
117:   VecCheckSameSize(x, 1, y, 2);
118:   VecCheckAssembled(x);
119:   VecCheckAssembled(y);

121:   PetscCall(VecLockReadPush(x));
122:   PetscCall(VecLockReadPush(y));
123:   PetscCall(PetscLogEventBegin(VEC_Dot, x, y, 0, 0));
124:   PetscUseTypeMethod(x, dot, y, val);
125:   PetscCall(PetscLogEventEnd(VEC_Dot, x, y, 0, 0));
126:   PetscCall(VecLockReadPop(x));
127:   PetscCall(VecLockReadPop(y));
128:   PetscFunctionReturn(PETSC_SUCCESS);
129: }

131: /*@
132:   VecDotRealPart - Computes the real part of the vector dot product.

134:   Collective

136:   Input Parameters:
137: + x - first vector
138: - y - second vector

140:   Output Parameter:
141: . val - the real part of the dot product;

143:   Level: intermediate

145:   Notes for Users of Complex Numbers:
146:   See `VecDot()` for more details on the definition of the dot product for complex numbers

148:   For real numbers this returns the same value as `VecDot()`

150:   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
151:   the space R^{2n} (that is a vector of 2n components with the real or imaginary part of the complex numbers for components)

153:   Developer Notes:
154:   This is not currently optimized to compute only the real part of the dot product.

156: .seealso: [](ch_vectors), `Vec`, `VecMDot()`, `VecTDot()`, `VecNorm()`, `VecDotBegin()`, `VecDotEnd()`, `VecDot()`, `VecDotNorm2()`
157: @*/
158: PetscErrorCode VecDotRealPart(Vec x, Vec y, PetscReal *val)
159: {
160:   PetscScalar fdot;

162:   PetscFunctionBegin;
163:   PetscCall(VecDot(x, y, &fdot));
164:   *val = PetscRealPart(fdot);
165:   PetscFunctionReturn(PETSC_SUCCESS);
166: }

168: /*@
169:   VecNorm  - Computes the vector norm.

171:   Collective

173:   Input Parameters:
174: + x    - the vector
175: - type - the type of the norm requested

177:   Output Parameter:
178: . val - the norm

180:   Level: intermediate

182:   Notes:
183:   See `NormType` for descriptions of each norm.

185:   For complex numbers `NORM_1` will return the traditional 1 norm of the 2 norm of the complex
186:   numbers; that is the 1 norm of the absolute values of the complex entries. In PETSc 3.6 and
187:   earlier releases it returned the 1 norm of the 1 norm of the complex entries (what is
188:   returned by the BLAS routine `asum()`). Both are valid norms but most people expect the former.

190:   This routine stashes the computed norm value, repeated calls before the vector entries are
191:   changed are then rapid since the precomputed value is immediately available. Certain vector
192:   operations such as `VecSet()` store the norms so the value is immediately available and does
193:   not need to be explicitly computed. `VecScale()` updates any stashed norm values, thus calls
194:   after `VecScale()` do not need to explicitly recompute the norm.

196: .seealso: [](ch_vectors), `Vec`, `NormType`, `VecDot()`, `VecTDot()`, `VecDotBegin()`, `VecDotEnd()`, `VecNormAvailable()`,
197:           `VecNormBegin()`, `VecNormEnd()`, `NormType()`
198: @*/
199: PetscErrorCode VecNorm(Vec x, NormType type, PetscReal *val)
200: {
201:   PetscBool flg = PETSC_TRUE;

203:   PetscFunctionBegin;
206:   VecCheckAssembled(x);
208:   PetscAssertPointer(val, 3);

210:   PetscCall(VecNormAvailable(x, type, &flg, val));
211:   // check that all MPI processes call this routine together and have same availability
212:   if (PetscDefined(USE_DEBUG)) {
213:     PetscMPIInt b0 = (PetscMPIInt)flg, b1[2], b2[2];
214:     b1[0]          = -b0;
215:     b1[1]          = b0;
216:     PetscCallMPI(MPIU_Allreduce(b1, b2, 2, MPI_INT, MPI_MAX, PetscObjectComm((PetscObject)x)));
217:     PetscCheck(-b2[0] == b2[1], PetscObjectComm((PetscObject)x), PETSC_ERR_ARG_WRONGSTATE, "Some MPI processes have cached %s norm, others do not. This may happen when some MPI processes call VecGetArray() and some others do not.", NormTypes[type]);
218:     if (flg) {
219:       PetscReal b1[2], b2[2];
220:       b1[0] = -(*val);
221:       b1[1] = *val;
222:       PetscCallMPI(MPIU_Allreduce(b1, b2, 2, MPIU_REAL, MPIU_MAX, PetscObjectComm((PetscObject)x)));
223:       PetscCheck((PetscIsNanReal(b2[0]) && PetscIsNanReal(b2[1])) || (-b2[0] == b2[1]), PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Difference in cached %s norms: local %g", NormTypes[type], (double)*val);
224:     }
225:   }
226:   if (flg) PetscFunctionReturn(PETSC_SUCCESS);

228:   PetscCall(VecLockReadPush(x));
229:   PetscCall(PetscLogEventBegin(VEC_Norm, x, 0, 0, 0));
230:   PetscUseTypeMethod(x, norm, type, val);
231:   PetscCall(PetscLogEventEnd(VEC_Norm, x, 0, 0, 0));
232:   PetscCall(VecLockReadPop(x));

234:   if (type != NORM_1_AND_2) PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[type], *val));
235:   PetscFunctionReturn(PETSC_SUCCESS);
236: }

238: /*@
239:   VecNormAvailable  - Returns the vector norm if it is already known. That is, it has been previously computed and cached in the vector

241:   Not Collective

243:   Input Parameters:
244: + x    - the vector
245: - type - one of `NORM_1` (sum_i |x[i]|), `NORM_2` sqrt(sum_i (x[i])^2), `NORM_INFINITY` max_i |x[i]|.  Also available
246:           `NORM_1_AND_2`, which computes both norms and stores them
247:           in a two element array.

249:   Output Parameters:
250: + available - `PETSC_TRUE` if the val returned is valid
251: - val       - the norm

253:   Level: intermediate

255:   Developer Notes:
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: [](ch_vectors), `Vec`, `VecDot()`, `VecTDot()`, `VecNorm()`, `VecDotBegin()`, `VecDotEnd()`,
261:           `VecNormBegin()`, `VecNormEnd()`
262: @*/
263: PetscErrorCode VecNormAvailable(Vec x, NormType type, PetscBool *available, PetscReal *val)
264: {
265:   PetscFunctionBegin;
268:   PetscAssertPointer(available, 3);
269:   PetscAssertPointer(val, 4);

271:   if (type == NORM_1_AND_2) {
272:     *available = PETSC_FALSE;
273:   } else {
274:     PetscCall(PetscObjectComposedDataGetReal((PetscObject)x, NormIds[type], *val, *available));
275:   }
276:   PetscFunctionReturn(PETSC_SUCCESS);
277: }

279: /*@
280:   VecNormalize - Normalizes a vector by its 2-norm.

282:   Collective

284:   Input Parameter:
285: . x - the vector

287:   Output Parameter:
288: . val - the vector norm before normalization. May be `NULL` if the value is not needed.

290:   Level: intermediate

292: .seealso: [](ch_vectors), `Vec`, `VecNorm()`, `NORM_2`, `NormType`
293: @*/
294: PetscErrorCode VecNormalize(Vec x, PetscReal *val)
295: {
296:   PetscReal norm;

298:   PetscFunctionBegin;
301:   PetscCall(VecSetErrorIfLocked(x, 1));
302:   if (val) PetscAssertPointer(val, 2);
303:   PetscCall(PetscLogEventBegin(VEC_Normalize, x, 0, 0, 0));
304:   PetscCall(VecNorm(x, NORM_2, &norm));
305:   if (norm == 0.0) PetscCall(PetscInfo(x, "Vector of zero norm can not be normalized; Returning only the zero norm\n"));
306:   else if (PetscIsInfOrNanReal(norm)) PetscCall(PetscInfo(x, "Vector with Inf or Nan norm can not be normalized; Returning only the norm\n"));
307:   else {
308:     PetscScalar s = 1.0 / norm;
309:     PetscCall(VecScale(x, s));
310:   }
311:   PetscCall(PetscLogEventEnd(VEC_Normalize, x, 0, 0, 0));
312:   if (val) *val = norm;
313:   PetscFunctionReturn(PETSC_SUCCESS);
314: }

316: /*@
317:   VecMax - Determines the vector component with maximum real part and its location.

319:   Collective

321:   Input Parameter:
322: . x - the vector

324:   Output Parameters:
325: + p   - the index of `val` (pass `NULL` if you don't want this) in the vector
326: - val - the maximum component

328:   Level: intermediate

330:   Notes:
331:   Returns the value `PETSC_MIN_REAL` and negative `p` if the vector is of length 0.

333:   Returns the smallest index with the maximum value

335:   Developer Note:
336:   The Nag Fortran compiler does not like the symbol name VecMax

338: .seealso: [](ch_vectors), `Vec`, `VecNorm()`, `VecMin()`
339: @*/
340: PetscErrorCode VecMax(Vec x, PetscInt *p, PetscReal *val)
341: {
342:   PetscFunctionBegin;
345:   VecCheckAssembled(x);
346:   if (p) PetscAssertPointer(p, 2);
347:   PetscAssertPointer(val, 3);
348:   PetscCall(VecLockReadPush(x));
349:   PetscCall(PetscLogEventBegin(VEC_Max, x, 0, 0, 0));
350:   PetscUseTypeMethod(x, max, p, val);
351:   PetscCall(PetscLogEventEnd(VEC_Max, x, 0, 0, 0));
352:   PetscCall(VecLockReadPop(x));
353:   PetscFunctionReturn(PETSC_SUCCESS);
354: }

356: /*@
357:   VecMin - Determines the vector component with minimum real part and its location.

359:   Collective

361:   Input Parameter:
362: . x - the vector

364:   Output Parameters:
365: + p   - the index of `val` (pass `NULL` if you don't want this location) in the vector
366: - val - the minimum component

368:   Level: intermediate

370:   Notes:
371:   Returns the value `PETSC_MAX_REAL` and negative `p` if the vector is of length 0.

373:   This returns the smallest index with the minimum value

375:   Developer Note:
376:   The Nag Fortran compiler does not like the symbol name VecMin

378: .seealso: [](ch_vectors), `Vec`, `VecMax()`
379: @*/
380: PetscErrorCode VecMin(Vec x, PetscInt *p, PetscReal *val)
381: {
382:   PetscFunctionBegin;
385:   VecCheckAssembled(x);
386:   if (p) PetscAssertPointer(p, 2);
387:   PetscAssertPointer(val, 3);
388:   PetscCall(VecLockReadPush(x));
389:   PetscCall(PetscLogEventBegin(VEC_Min, x, 0, 0, 0));
390:   PetscUseTypeMethod(x, min, p, val);
391:   PetscCall(PetscLogEventEnd(VEC_Min, x, 0, 0, 0));
392:   PetscCall(VecLockReadPop(x));
393:   PetscFunctionReturn(PETSC_SUCCESS);
394: }

396: /*@
397:   VecTDot - Computes an indefinite vector dot product. That is, this
398:   routine does NOT use the complex conjugate.

400:   Collective

402:   Input Parameters:
403: + x - first vector
404: - y - second vector

406:   Output Parameter:
407: . val - the dot product

409:   Level: intermediate

411:   Notes for Users of Complex Numbers:
412:   For complex vectors, `VecTDot()` computes the indefinite form
413: .vb
414:   val = (x,y) = y^T x,
415: .ve
416:   where y^T denotes the transpose of y.

418:   Use `VecDot()` for the inner product
419: .vb
420:   val = (x,y) = y^H x,
421: .ve
422:   where y^H denotes the conjugate transpose of y.

424: .seealso: [](ch_vectors), `Vec`, `VecDot()`, `VecMTDot()`
425: @*/
426: PetscErrorCode VecTDot(Vec x, Vec y, PetscScalar *val)
427: {
428:   PetscFunctionBegin;
431:   PetscAssertPointer(val, 3);
434:   PetscCheckSameTypeAndComm(x, 1, y, 2);
435:   VecCheckSameSize(x, 1, y, 2);
436:   VecCheckAssembled(x);
437:   VecCheckAssembled(y);

439:   PetscCall(VecLockReadPush(x));
440:   PetscCall(VecLockReadPush(y));
441:   PetscCall(PetscLogEventBegin(VEC_TDot, x, y, 0, 0));
442:   PetscUseTypeMethod(x, tdot, y, val);
443:   PetscCall(PetscLogEventEnd(VEC_TDot, x, y, 0, 0));
444:   PetscCall(VecLockReadPop(x));
445:   PetscCall(VecLockReadPop(y));
446:   PetscFunctionReturn(PETSC_SUCCESS);
447: }

449: PetscErrorCode VecScaleAsync_Private(Vec x, PetscScalar alpha, PetscDeviceContext dctx)
450: {
451:   PetscReal   norms[4];
452:   PetscBool   flgs[4];
453:   PetscScalar one = 1.0;

455:   PetscFunctionBegin;
458:   VecCheckAssembled(x);
459:   PetscCall(VecSetErrorIfLocked(x, 1));
461:   if (alpha == one) PetscFunctionReturn(PETSC_SUCCESS);

463:   /* get current stashed norms */
464:   for (PetscInt i = 0; i < 4; i++) PetscCall(PetscObjectComposedDataGetReal((PetscObject)x, NormIds[i], norms[i], flgs[i]));

466:   PetscCall(PetscLogEventBegin(VEC_Scale, x, 0, 0, 0));
467:   VecMethodDispatch(x, dctx, VecAsyncFnName(Scale), scale, (Vec, PetscScalar, PetscDeviceContext), alpha);
468:   PetscCall(PetscLogEventEnd(VEC_Scale, x, 0, 0, 0));

470:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
471:   /* put the scaled stashed norms back into the Vec */
472:   for (PetscInt i = 0; i < 4; i++) {
473:     PetscReal ar = PetscAbsScalar(alpha);
474:     if (flgs[i]) PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[i], ar * norms[i]));
475:   }
476:   PetscFunctionReturn(PETSC_SUCCESS);
477: }

479: /*@
480:   VecScale - Scales a vector.

482:   Logically Collective

484:   Input Parameters:
485: + x     - the vector
486: - alpha - the scalar

488:   Level: intermediate

490:   Note:
491:   For a vector with n components, `VecScale()` computes  x[i] = alpha * x[i], for i=1,...,n.

493: .seealso: [](ch_vectors), `Vec`, `VecSet()`
494: @*/
495: PetscErrorCode VecScale(Vec x, PetscScalar alpha)
496: {
497:   PetscFunctionBegin;
498:   PetscCall(VecScaleAsync_Private(x, alpha, NULL));
499:   PetscFunctionReturn(PETSC_SUCCESS);
500: }

502: PetscErrorCode VecSetAsync_Private(Vec x, PetscScalar alpha, PetscDeviceContext dctx)
503: {
504:   PetscFunctionBegin;
507:   VecCheckAssembled(x);
509:   PetscCall(VecSetErrorIfLocked(x, 1));

511:   if (alpha == 0) {
512:     PetscReal norm;
513:     PetscBool set;

515:     PetscCall(VecNormAvailable(x, NORM_2, &set, &norm));
516:     if (set == PETSC_TRUE && norm == 0) PetscFunctionReturn(PETSC_SUCCESS);
517:   }
518:   PetscCall(PetscLogEventBegin(VEC_Set, x, 0, 0, 0));
519:   VecMethodDispatch(x, dctx, VecAsyncFnName(Set), set, (Vec, PetscScalar, PetscDeviceContext), alpha);
520:   PetscCall(PetscLogEventEnd(VEC_Set, x, 0, 0, 0));
521:   PetscCall(PetscObjectStateIncrease((PetscObject)x));

523:   /*  norms can be simply set (if |alpha|*N not too large) */
524:   {
525:     PetscReal      val = PetscAbsScalar(alpha);
526:     const PetscInt N   = x->map->N;

528:     if (N == 0) {
529:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_1], 0.0));
530:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_INFINITY], 0.0));
531:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_2], 0.0));
532:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_FROBENIUS], 0.0));
533:     } else if (val > PETSC_MAX_REAL / N) {
534:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_INFINITY], val));
535:     } else {
536:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_1], N * val));
537:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_INFINITY], val));
538:       val *= PetscSqrtReal((PetscReal)N);
539:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_2], val));
540:       PetscCall(PetscObjectComposedDataSetReal((PetscObject)x, NormIds[NORM_FROBENIUS], val));
541:     }
542:   }
543:   PetscFunctionReturn(PETSC_SUCCESS);
544: }

546: /*@
547:   VecSet - Sets all components of a vector to a single scalar value.

549:   Logically Collective

551:   Input Parameters:
552: + x     - the vector
553: - alpha - the scalar

555:   Level: beginner

557:   Notes:
558:   For a vector of dimension n, `VecSet()` sets x[i] = alpha, for i=1,...,n,
559:   so that all vector entries then equal the identical
560:   scalar value, `alpha`.  Use the more general routine
561:   `VecSetValues()` to set different vector entries.

563:   You CANNOT call this after you have called `VecSetValues()` but before you call
564:   `VecAssemblyBegin()`

566:   If `alpha` is zero and the norm of the vector is known to be zero then this skips the unneeded zeroing process

568: .seealso: [](ch_vectors), `Vec`, `VecSetValues()`, `VecSetValuesBlocked()`, `VecSetRandom()`
569: @*/
570: PetscErrorCode VecSet(Vec x, PetscScalar alpha)
571: {
572:   PetscFunctionBegin;
573:   PetscCall(VecSetAsync_Private(x, alpha, NULL));
574:   PetscFunctionReturn(PETSC_SUCCESS);
575: }

577: PetscErrorCode VecAXPYAsync_Private(Vec y, PetscScalar alpha, Vec x, PetscDeviceContext dctx)
578: {
579:   PetscFunctionBegin;
584:   PetscCheckSameTypeAndComm(x, 3, y, 1);
585:   VecCheckSameSize(x, 3, y, 1);
586:   VecCheckAssembled(x);
587:   VecCheckAssembled(y);
589:   if (alpha == (PetscScalar)0.0) PetscFunctionReturn(PETSC_SUCCESS);
590:   PetscCall(VecSetErrorIfLocked(y, 1));
591:   if (x == y) {
592:     PetscCall(VecScale(y, alpha + 1.0));
593:     PetscFunctionReturn(PETSC_SUCCESS);
594:   }
595:   PetscCall(VecLockReadPush(x));
596:   PetscCall(PetscLogEventBegin(VEC_AXPY, x, y, 0, 0));
597:   VecMethodDispatch(y, dctx, VecAsyncFnName(AXPY), axpy, (Vec, PetscScalar, Vec, PetscDeviceContext), alpha, x);
598:   PetscCall(PetscLogEventEnd(VEC_AXPY, x, y, 0, 0));
599:   PetscCall(VecLockReadPop(x));
600:   PetscCall(PetscObjectStateIncrease((PetscObject)y));
601:   PetscFunctionReturn(PETSC_SUCCESS);
602: }
603: /*@
604:   VecAXPY - Computes `y = alpha x + y`.

606:   Logically Collective

608:   Input Parameters:
609: + alpha - the scalar
610: . x     - vector scale by `alpha`
611: - y     - vector accumulated into

613:   Output Parameter:
614: . y - output vector

616:   Level: intermediate

618:   Notes:
619:   This routine is optimized for alpha of 0.0, otherwise it calls the BLAS routine
620: .vb
621:     VecAXPY(y,alpha,x)                   y = alpha x           +      y
622:     VecAYPX(y,beta,x)                    y =       x           + beta y
623:     VecAXPBY(y,alpha,beta,x)             y = alpha x           + beta y
624:     VecWAXPY(w,alpha,x,y)                w = alpha x           +      y
625:     VecAXPBYPCZ(z,alpha,beta,gamma,x,y)  z = alpha x           + beta y + gamma z
626:     VecMAXPY(y,nv,alpha[],x[])           y = sum alpha[i] x[i] +      y
627: .ve

629: .seealso: [](ch_vectors), `Vec`, `VecAYPX()`, `VecMAXPY()`, `VecWAXPY()`, `VecAXPBYPCZ()`, `VecAXPBY()`
630: @*/
631: PetscErrorCode VecAXPY(Vec y, PetscScalar alpha, Vec x)
632: {
633:   PetscFunctionBegin;
634:   PetscCall(VecAXPYAsync_Private(y, alpha, x, NULL));
635:   PetscFunctionReturn(PETSC_SUCCESS);
636: }

638: PetscErrorCode VecAYPXAsync_Private(Vec y, PetscScalar beta, Vec x, PetscDeviceContext dctx)
639: {
640:   PetscFunctionBegin;
645:   PetscCheckSameTypeAndComm(x, 3, y, 1);
646:   VecCheckSameSize(x, 1, y, 3);
647:   VecCheckAssembled(x);
648:   VecCheckAssembled(y);
650:   PetscCall(VecSetErrorIfLocked(y, 1));
651:   if (x == y) {
652:     PetscCall(VecScale(y, beta + 1.0));
653:     PetscFunctionReturn(PETSC_SUCCESS);
654:   }
655:   PetscCall(VecLockReadPush(x));
656:   if (beta == (PetscScalar)0.0) {
657:     PetscCall(VecCopy(x, y));
658:   } else {
659:     PetscCall(PetscLogEventBegin(VEC_AYPX, x, y, 0, 0));
660:     VecMethodDispatch(y, dctx, VecAsyncFnName(AYPX), aypx, (Vec, PetscScalar, Vec, PetscDeviceContext), beta, x);
661:     PetscCall(PetscLogEventEnd(VEC_AYPX, x, y, 0, 0));
662:     PetscCall(PetscObjectStateIncrease((PetscObject)y));
663:   }
664:   PetscCall(VecLockReadPop(x));
665:   PetscFunctionReturn(PETSC_SUCCESS);
666: }

668: /*@
669:   VecAYPX - Computes `y = x + beta y`.

671:   Logically Collective

673:   Input Parameters:
674: + beta - the scalar
675: . x    - the unscaled vector
676: - y    - the vector to be scaled

678:   Output Parameter:
679: . y - output vector

681:   Level: intermediate

683:   Developer Notes:
684:   The implementation is optimized for `beta` of -1.0, 0.0, and 1.0

686: .seealso: [](ch_vectors), `Vec`, `VecMAXPY()`, `VecWAXPY()`, `VecAXPY()`, `VecAXPBYPCZ()`, `VecAXPBY()`
687: @*/
688: PetscErrorCode VecAYPX(Vec y, PetscScalar beta, Vec x)
689: {
690:   PetscFunctionBegin;
691:   PetscCall(VecAYPXAsync_Private(y, beta, x, NULL));
692:   PetscFunctionReturn(PETSC_SUCCESS);
693: }

695: PetscErrorCode VecAXPBYAsync_Private(Vec y, PetscScalar alpha, PetscScalar beta, Vec x, PetscDeviceContext dctx)
696: {
697:   PetscFunctionBegin;
702:   PetscCheckSameTypeAndComm(x, 4, y, 1);
703:   VecCheckSameSize(y, 1, x, 4);
704:   VecCheckAssembled(x);
705:   VecCheckAssembled(y);
708:   if (alpha == (PetscScalar)0.0 && beta == (PetscScalar)1.0) PetscFunctionReturn(PETSC_SUCCESS);
709:   if (x == y) {
710:     PetscCall(VecScale(y, alpha + beta));
711:     PetscFunctionReturn(PETSC_SUCCESS);
712:   }

714:   PetscCall(VecSetErrorIfLocked(y, 1));
715:   PetscCall(VecLockReadPush(x));
716:   PetscCall(PetscLogEventBegin(VEC_AXPY, y, x, 0, 0));
717:   VecMethodDispatch(y, dctx, VecAsyncFnName(AXPBY), axpby, (Vec, PetscScalar, PetscScalar, Vec, PetscDeviceContext), alpha, beta, x);
718:   PetscCall(PetscLogEventEnd(VEC_AXPY, y, x, 0, 0));
719:   PetscCall(PetscObjectStateIncrease((PetscObject)y));
720:   PetscCall(VecLockReadPop(x));
721:   PetscFunctionReturn(PETSC_SUCCESS);
722: }

724: /*@
725:   VecAXPBY - Computes `y = alpha x + beta y`.

727:   Logically Collective

729:   Input Parameters:
730: + alpha - first scalar
731: . beta  - second scalar
732: . x     - the first scaled vector
733: - y     - the second scaled vector

735:   Output Parameter:
736: . y - output vector

738:   Level: intermediate

740:   Developer Notes:
741:   The implementation is optimized for `alpha` and/or `beta` values of 0.0 and 1.0

743: .seealso: [](ch_vectors), `Vec`, `VecAYPX()`, `VecMAXPY()`, `VecWAXPY()`, `VecAXPY()`, `VecAXPBYPCZ()`
744: @*/
745: PetscErrorCode VecAXPBY(Vec y, PetscScalar alpha, PetscScalar beta, Vec x)
746: {
747:   PetscFunctionBegin;
748:   PetscCall(VecAXPBYAsync_Private(y, alpha, beta, x, NULL));
749:   PetscFunctionReturn(PETSC_SUCCESS);
750: }

752: PetscErrorCode VecAXPBYPCZAsync_Private(Vec z, PetscScalar alpha, PetscScalar beta, PetscScalar gamma, Vec x, Vec y, PetscDeviceContext dctx)
753: {
754:   PetscFunctionBegin;
761:   PetscCheckSameTypeAndComm(x, 5, y, 6);
762:   PetscCheckSameTypeAndComm(x, 5, z, 1);
763:   VecCheckSameSize(x, 5, y, 6);
764:   VecCheckSameSize(x, 5, z, 1);
765:   PetscCheck(x != y && x != z, PetscObjectComm((PetscObject)x), PETSC_ERR_ARG_IDN, "x, y, and z must be different vectors");
766:   PetscCheck(y != z, PetscObjectComm((PetscObject)y), PETSC_ERR_ARG_IDN, "x, y, and z must be different vectors");
767:   VecCheckAssembled(x);
768:   VecCheckAssembled(y);
769:   VecCheckAssembled(z);
773:   if (alpha == (PetscScalar)0.0 && beta == (PetscScalar)0.0 && gamma == (PetscScalar)1.0) PetscFunctionReturn(PETSC_SUCCESS);

775:   PetscCall(VecSetErrorIfLocked(z, 1));
776:   PetscCall(VecLockReadPush(x));
777:   PetscCall(VecLockReadPush(y));
778:   PetscCall(PetscLogEventBegin(VEC_AXPBYPCZ, x, y, z, 0));
779:   VecMethodDispatch(z, dctx, VecAsyncFnName(AXPBYPCZ), axpbypcz, (Vec, PetscScalar, PetscScalar, PetscScalar, Vec, Vec, PetscDeviceContext), alpha, beta, gamma, x, y);
780:   PetscCall(PetscLogEventEnd(VEC_AXPBYPCZ, x, y, z, 0));
781:   PetscCall(PetscObjectStateIncrease((PetscObject)z));
782:   PetscCall(VecLockReadPop(x));
783:   PetscCall(VecLockReadPop(y));
784:   PetscFunctionReturn(PETSC_SUCCESS);
785: }
786: /*@
787:   VecAXPBYPCZ - Computes `z = alpha x + beta y + gamma z`

789:   Logically Collective

791:   Input Parameters:
792: + alpha - first scalar
793: . beta  - second scalar
794: . gamma - third scalar
795: . x     - first vector
796: . y     - second vector
797: - z     - third vector

799:   Output Parameter:
800: . z - output vector

802:   Level: intermediate

804:   Note:
805:   `x`, `y` and `z` must be different vectors

807:   Developer Notes:
808:   The implementation is optimized for `alpha` of 1.0 and `gamma` of 1.0 or 0.0

810: .seealso: [](ch_vectors), `Vec`, `VecAYPX()`, `VecMAXPY()`, `VecWAXPY()`, `VecAXPY()`, `VecAXPBY()`
811: @*/
812: PetscErrorCode VecAXPBYPCZ(Vec z, PetscScalar alpha, PetscScalar beta, PetscScalar gamma, Vec x, Vec y)
813: {
814:   PetscFunctionBegin;
815:   PetscCall(VecAXPBYPCZAsync_Private(z, alpha, beta, gamma, x, y, NULL));
816:   PetscFunctionReturn(PETSC_SUCCESS);
817: }

819: PetscErrorCode VecWAXPYAsync_Private(Vec w, PetscScalar alpha, Vec x, Vec y, PetscDeviceContext dctx)
820: {
821:   PetscFunctionBegin;
828:   PetscCheckSameTypeAndComm(x, 3, y, 4);
829:   PetscCheckSameTypeAndComm(y, 4, w, 1);
830:   VecCheckSameSize(x, 3, y, 4);
831:   VecCheckSameSize(x, 3, w, 1);
832:   PetscCheck(w != y, PETSC_COMM_SELF, PETSC_ERR_SUP, "Result vector w cannot be same as input vector y, suggest VecAXPY()");
833:   PetscCheck(w != x, PETSC_COMM_SELF, PETSC_ERR_SUP, "Result vector w cannot be same as input vector x, suggest VecAYPX()");
834:   VecCheckAssembled(x);
835:   VecCheckAssembled(y);
837:   PetscCall(VecSetErrorIfLocked(w, 1));

839:   PetscCall(VecLockReadPush(x));
840:   PetscCall(VecLockReadPush(y));
841:   if (alpha == (PetscScalar)0.0) {
842:     PetscCall(VecCopyAsync_Private(y, w, dctx));
843:   } else {
844:     PetscCall(PetscLogEventBegin(VEC_WAXPY, x, y, w, 0));
845:     VecMethodDispatch(w, dctx, VecAsyncFnName(WAXPY), waxpy, (Vec, PetscScalar, Vec, Vec, PetscDeviceContext), alpha, x, y);
846:     PetscCall(PetscLogEventEnd(VEC_WAXPY, x, y, w, 0));
847:     PetscCall(PetscObjectStateIncrease((PetscObject)w));
848:   }
849:   PetscCall(VecLockReadPop(x));
850:   PetscCall(VecLockReadPop(y));
851:   PetscFunctionReturn(PETSC_SUCCESS);
852: }

854: /*@
855:   VecWAXPY - Computes `w = alpha x + y`.

857:   Logically Collective

859:   Input Parameters:
860: + alpha - the scalar
861: . x     - first vector, multiplied by `alpha`
862: - y     - second vector

864:   Output Parameter:
865: . w - the result

867:   Level: intermediate

869:   Note:
870:   `w` cannot be either `x` or `y`, but `x` and `y` can be the same

872:   Developer Notes:
873:   The implementation is optimized for alpha of -1.0, 0.0, and 1.0

875: .seealso: [](ch_vectors), `Vec`, `VecAXPY()`, `VecAYPX()`, `VecAXPBY()`, `VecMAXPY()`, `VecAXPBYPCZ()`
876: @*/
877: PetscErrorCode VecWAXPY(Vec w, PetscScalar alpha, Vec x, Vec y)
878: {
879:   PetscFunctionBegin;
880:   PetscCall(VecWAXPYAsync_Private(w, alpha, x, y, NULL));
881:   PetscFunctionReturn(PETSC_SUCCESS);
882: }

884: /*@
885:   VecSetValues - Inserts or adds values into certain locations of a vector.

887:   Not Collective

889:   Input Parameters:
890: + x    - vector to insert in
891: . ni   - number of elements to add
892: . ix   - indices where to add
893: . y    - array of values
894: - iora - either `INSERT_VALUES` to replace the current values or `ADD_VALUES` to add values to any existing entries

896:   Level: beginner

898:   Notes:
899: .vb
900:    `VecSetValues()` sets x[ix[i]] = y[i], for i=0,...,ni-1.
901: .ve

903:   Calls to `VecSetValues()` with the `INSERT_VALUES` and `ADD_VALUES`
904:   options cannot be mixed without intervening calls to the assembly
905:   routines.

907:   These values may be cached, so `VecAssemblyBegin()` and `VecAssemblyEnd()`
908:   MUST be called after all calls to `VecSetValues()` have been completed.

910:   VecSetValues() uses 0-based indices in Fortran as well as in C.

912:   If you call `VecSetOption`(x, `VEC_IGNORE_NEGATIVE_INDICES`,`PETSC_TRUE`),
913:   negative indices may be passed in ix. These rows are
914:   simply ignored. This allows easily inserting element load matrices
915:   with homogeneous Dirichlet boundary conditions that you don't want represented
916:   in the vector.

918:   Fortran Note:
919:   If any of `ix` and `y` are scalars pass them using, for example,
920: .vb
921:   call VecSetValues(mat, one, [ix], [y], INSERT_VALUES, ierr)
922: .ve

924: .seealso: [](ch_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValuesLocal()`,
925:           `VecSetValue()`, `VecSetValuesBlocked()`, `InsertMode`, `INSERT_VALUES`, `ADD_VALUES`, `VecGetValues()`
926: @*/
927: PetscErrorCode VecSetValues(Vec x, PetscInt ni, const PetscInt ix[], const PetscScalar y[], InsertMode iora)
928: {
929:   PetscFunctionBeginHot;
931:   if (!ni) PetscFunctionReturn(PETSC_SUCCESS);
932:   PetscAssertPointer(ix, 3);
933:   PetscAssertPointer(y, 4);

936:   PetscCall(PetscLogEventBegin(VEC_SetValues, x, 0, 0, 0));
937:   PetscUseTypeMethod(x, setvalues, ni, ix, y, iora);
938:   PetscCall(PetscLogEventEnd(VEC_SetValues, x, 0, 0, 0));
939:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
940:   PetscFunctionReturn(PETSC_SUCCESS);
941: }

943: /*@
944:   VecGetValues - Gets values from certain locations of a vector. Currently
945:   can only get values on the same processor on which they are owned

947:   Not Collective

949:   Input Parameters:
950: + x  - vector to get values from
951: . ni - number of elements to get
952: - ix - indices where to get them from (in global 1d numbering)

954:   Output Parameter:
955: . y - array of values, must be passed in with a length of `ni`

957:   Level: beginner

959:   Notes:
960:   The user provides the allocated array y; it is NOT allocated in this routine

962:   `VecGetValues()` gets y[i] = x[ix[i]], for i=0,...,ni-1.

964:   `VecAssemblyBegin()` and `VecAssemblyEnd()`  MUST be called before calling this if `VecSetValues()` or related routine has been called

966:   VecGetValues() uses 0-based indices in Fortran as well as in C.

968:   If you call `VecSetOption`(x, `VEC_IGNORE_NEGATIVE_INDICES`,`PETSC_TRUE`),
969:   negative indices may be passed in ix. These rows are
970:   simply ignored.

972: .seealso: [](ch_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValues()`
973: @*/
974: PetscErrorCode VecGetValues(Vec x, PetscInt ni, const PetscInt ix[], PetscScalar y[])
975: {
976:   PetscFunctionBegin;
978:   if (!ni) PetscFunctionReturn(PETSC_SUCCESS);
979:   PetscAssertPointer(ix, 3);
980:   PetscAssertPointer(y, 4);
982:   VecCheckAssembled(x);
983:   PetscUseTypeMethod(x, getvalues, ni, ix, y);
984:   PetscFunctionReturn(PETSC_SUCCESS);
985: }

987: /*@
988:   VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector.

990:   Not Collective

992:   Input Parameters:
993: + x    - vector to insert in
994: . ni   - number of blocks to add
995: . ix   - indices where to add in block count, rather than element count
996: . y    - array of values
997: - iora - either `INSERT_VALUES` replaces existing entries with new values, `ADD_VALUES`, adds values to any existing entries

999:   Level: intermediate

1001:   Notes:
1002:   `VecSetValuesBlocked()` sets x[bs*ix[i]+j] = y[bs*i+j],
1003:   for j=0,...,bs-1, for i=0,...,ni-1. where bs was set with VecSetBlockSize().

1005:   Calls to `VecSetValuesBlocked()` with the `INSERT_VALUES` and `ADD_VALUES`
1006:   options cannot be mixed without intervening calls to the assembly
1007:   routines.

1009:   These values may be cached, so `VecAssemblyBegin()` and `VecAssemblyEnd()`
1010:   MUST be called after all calls to `VecSetValuesBlocked()` have been completed.

1012:   `VecSetValuesBlocked()` uses 0-based indices in Fortran as well as in C.

1014:   Negative indices may be passed in ix, these rows are
1015:   simply ignored. This allows easily inserting element load matrices
1016:   with homogeneous Dirichlet boundary conditions that you don't want represented
1017:   in the vector.

1019:   Fortran Note:
1020:   If any of `ix` and `y` are scalars pass them using, for example,
1021: .vb
1022:   call VecSetValuesBlocked(mat, one, [ix], [y], INSERT_VALUES, ierr)
1023: .ve

1025: .seealso: [](ch_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValuesBlockedLocal()`,
1026:           `VecSetValues()`
1027: @*/
1028: PetscErrorCode VecSetValuesBlocked(Vec x, PetscInt ni, const PetscInt ix[], const PetscScalar y[], InsertMode iora)
1029: {
1030:   PetscFunctionBeginHot;
1032:   if (!ni) PetscFunctionReturn(PETSC_SUCCESS);
1033:   PetscAssertPointer(ix, 3);
1034:   PetscAssertPointer(y, 4);

1037:   PetscCall(PetscLogEventBegin(VEC_SetValues, x, 0, 0, 0));
1038:   PetscUseTypeMethod(x, setvaluesblocked, ni, ix, y, iora);
1039:   PetscCall(PetscLogEventEnd(VEC_SetValues, x, 0, 0, 0));
1040:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
1041:   PetscFunctionReturn(PETSC_SUCCESS);
1042: }

1044: /*@
1045:   VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1046:   using a local ordering of the nodes.

1048:   Not Collective

1050:   Input Parameters:
1051: + x    - vector to insert in
1052: . ni   - number of elements to add
1053: . ix   - indices where to add
1054: . y    - array of values
1055: - iora - either `INSERT_VALUES` replaces existing entries with new values, `ADD_VALUES` adds values to any existing entries

1057:   Level: intermediate

1059:   Notes:
1060:   `VecSetValuesLocal()` sets x[ix[i]] = y[i], for i=0,...,ni-1.

1062:   Calls to `VecSetValuesLocal()` with the `INSERT_VALUES` and `ADD_VALUES`
1063:   options cannot be mixed without intervening calls to the assembly
1064:   routines.

1066:   These values may be cached, so `VecAssemblyBegin()` and `VecAssemblyEnd()`
1067:   MUST be called after all calls to `VecSetValuesLocal()` have been completed.

1069:   `VecSetValuesLocal()` uses 0-based indices in Fortran as well as in C.

1071:   Fortran Note:
1072:   If any of `ix` and `y` are scalars pass them using, for example,
1073: .vb
1074:   call VecSetValuesLocal(mat, one, [ix], [y], INSERT_VALUES, ierr)
1075: .ve

1077: .seealso: [](ch_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValues()`, `VecSetLocalToGlobalMapping()`,
1078:           `VecSetValuesBlockedLocal()`
1079: @*/
1080: PetscErrorCode VecSetValuesLocal(Vec x, PetscInt ni, const PetscInt ix[], const PetscScalar y[], InsertMode iora)
1081: {
1082:   PetscInt lixp[128], *lix = lixp;

1084:   PetscFunctionBeginHot;
1086:   if (!ni) PetscFunctionReturn(PETSC_SUCCESS);
1087:   PetscAssertPointer(ix, 3);
1088:   PetscAssertPointer(y, 4);

1091:   PetscCall(PetscLogEventBegin(VEC_SetValues, x, 0, 0, 0));
1092:   if (!x->ops->setvalueslocal) {
1093:     if (PetscUnlikely(!x->map->mapping && x->ops->getlocaltoglobalmapping)) PetscUseTypeMethod(x, getlocaltoglobalmapping, &x->map->mapping);
1094:     if (x->map->mapping) {
1095:       if (ni > 128) PetscCall(PetscMalloc1(ni, &lix));
1096:       PetscCall(ISLocalToGlobalMappingApply(x->map->mapping, ni, (PetscInt *)ix, lix));
1097:       PetscUseTypeMethod(x, setvalues, ni, lix, y, iora);
1098:       if (ni > 128) PetscCall(PetscFree(lix));
1099:     } else PetscUseTypeMethod(x, setvalues, ni, ix, y, iora);
1100:   } else PetscUseTypeMethod(x, setvalueslocal, ni, ix, y, iora);
1101:   PetscCall(PetscLogEventEnd(VEC_SetValues, x, 0, 0, 0));
1102:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
1103:   PetscFunctionReturn(PETSC_SUCCESS);
1104: }

1106: /*@
1107:   VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1108:   using a local ordering of the nodes.

1110:   Not Collective

1112:   Input Parameters:
1113: + x    - vector to insert in
1114: . ni   - number of blocks to add
1115: . ix   - indices where to add in block count, not element count
1116: . y    - array of values
1117: - iora - either `INSERT_VALUES` replaces existing entries with new values, `ADD_VALUES` adds values to any existing entries

1119:   Level: intermediate

1121:   Notes:
1122:   `VecSetValuesBlockedLocal()` sets x[bs*ix[i]+j] = y[bs*i+j],
1123:   for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with `VecSetBlockSize()`.

1125:   Calls to `VecSetValuesBlockedLocal()` with the `INSERT_VALUES` and `ADD_VALUES`
1126:   options cannot be mixed without intervening calls to the assembly
1127:   routines.

1129:   These values may be cached, so `VecAssemblyBegin()` and `VecAssemblyEnd()`
1130:   MUST be called after all calls to `VecSetValuesBlockedLocal()` have been completed.

1132:   `VecSetValuesBlockedLocal()` uses 0-based indices in Fortran as well as in C.

1134:   Fortran Note:
1135:   If any of `ix` and `y` are scalars pass them using, for example,
1136: .vb
1137:   call VecSetValuesBlockedLocal(mat, one, [ix], [y], INSERT_VALUES, ierr)
1138: .ve

1140: .seealso: [](ch_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValues()`, `VecSetValuesBlocked()`,
1141:           `VecSetLocalToGlobalMapping()`
1142: @*/
1143: PetscErrorCode VecSetValuesBlockedLocal(Vec x, PetscInt ni, const PetscInt ix[], const PetscScalar y[], InsertMode iora)
1144: {
1145:   PetscInt lixp[128], *lix = lixp;

1147:   PetscFunctionBeginHot;
1149:   if (!ni) PetscFunctionReturn(PETSC_SUCCESS);
1150:   PetscAssertPointer(ix, 3);
1151:   PetscAssertPointer(y, 4);
1153:   PetscCall(PetscLogEventBegin(VEC_SetValues, x, 0, 0, 0));
1154:   if (PetscUnlikely(!x->map->mapping && x->ops->getlocaltoglobalmapping)) PetscUseTypeMethod(x, getlocaltoglobalmapping, &x->map->mapping);
1155:   if (x->map->mapping) {
1156:     if (ni > 128) PetscCall(PetscMalloc1(ni, &lix));
1157:     PetscCall(ISLocalToGlobalMappingApplyBlock(x->map->mapping, ni, (PetscInt *)ix, lix));
1158:     PetscUseTypeMethod(x, setvaluesblocked, ni, lix, y, iora);
1159:     if (ni > 128) PetscCall(PetscFree(lix));
1160:   } else {
1161:     PetscUseTypeMethod(x, setvaluesblocked, ni, ix, y, iora);
1162:   }
1163:   PetscCall(PetscLogEventEnd(VEC_SetValues, x, 0, 0, 0));
1164:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
1165:   PetscFunctionReturn(PETSC_SUCCESS);
1166: }

1168: static PetscErrorCode VecMXDot_Private(Vec x, PetscInt nv, const Vec y[], PetscScalar result[], PetscErrorCode (*mxdot)(Vec, PetscInt, const Vec[], PetscScalar[]), PetscLogEvent event)
1169: {
1170:   PetscFunctionBegin;
1173:   VecCheckAssembled(x);
1175:   if (!nv) PetscFunctionReturn(PETSC_SUCCESS);
1176:   PetscAssertPointer(y, 3);
1177:   for (PetscInt i = 0; i < nv; ++i) {
1180:     PetscCheckSameTypeAndComm(x, 1, y[i], 3);
1181:     VecCheckSameSize(x, 1, y[i], 3);
1182:     VecCheckAssembled(y[i]);
1183:     PetscCall(VecLockReadPush(y[i]));
1184:   }
1185:   PetscAssertPointer(result, 4);

1188:   PetscCall(VecLockReadPush(x));
1189:   PetscCall(PetscLogEventBegin(event, x, *y, 0, 0));
1190:   PetscCall((*mxdot)(x, nv, y, result));
1191:   PetscCall(PetscLogEventEnd(event, x, *y, 0, 0));
1192:   PetscCall(VecLockReadPop(x));
1193:   for (PetscInt i = 0; i < nv; ++i) PetscCall(VecLockReadPop(y[i]));
1194:   PetscFunctionReturn(PETSC_SUCCESS);
1195: }

1197: /*@
1198:   VecMTDot - Computes indefinite vector multiple dot products.
1199:   That is, it does NOT use the complex conjugate.

1201:   Collective

1203:   Input Parameters:
1204: + x  - one vector
1205: . nv - number of vectors
1206: - y  - array of vectors.  Note that vectors are pointers

1208:   Output Parameter:
1209: . val - array of the dot products

1211:   Level: intermediate

1213:   Notes for Users of Complex Numbers:
1214:   For complex vectors, `VecMTDot()` computes the indefinite form
1215: .vb
1216:   val = (x,y) = y^T x,
1217: .ve
1218:   where y^T denotes the transpose of y.

1220:   Use `VecMDot()` for the inner product
1221: .vb
1222:   val = (x,y) = y^H x,
1223: .ve
1224:   where y^H denotes the conjugate transpose of y.

1226: .seealso: [](ch_vectors), `Vec`, `VecMDot()`, `VecTDot()`
1227: @*/
1228: PetscErrorCode VecMTDot(Vec x, PetscInt nv, const Vec y[], PetscScalar val[])
1229: {
1230:   PetscFunctionBegin;
1232:   PetscCall(VecMXDot_Private(x, nv, y, val, x->ops->mtdot, VEC_MTDot));
1233:   PetscFunctionReturn(PETSC_SUCCESS);
1234: }

1236: /*@
1237:   VecMDot - Computes multiple vector dot products.

1239:   Collective

1241:   Input Parameters:
1242: + x  - one vector
1243: . nv - number of vectors
1244: - y  - array of vectors.

1246:   Output Parameter:
1247: . val - array of the dot products (does not allocate the array)

1249:   Level: intermediate

1251:   Notes for Users of Complex Numbers:
1252:   For complex vectors, `VecMDot()` computes
1253: .vb
1254:   val = (x,y) = y^H x,
1255: .ve
1256:   where y^H denotes the conjugate transpose of y.

1258:   Use `VecMTDot()` for the indefinite form
1259: .vb
1260:   val = (x,y) = y^T x,
1261: .ve
1262:   where y^T denotes the transpose of y.

1264:   Note:
1265:   The implementation may use BLAS 2 operations when the vectors `y` have been obtained with `VecDuplicateVecs()`

1267: .seealso: [](ch_vectors), `Vec`, `VecMTDot()`, `VecDot()`, `VecDuplicateVecs()`
1268: @*/
1269: PetscErrorCode VecMDot(Vec x, PetscInt nv, const Vec y[], PetscScalar val[])
1270: {
1271:   PetscFunctionBegin;
1273:   PetscCall(VecMXDot_Private(x, nv, y, val, x->ops->mdot, VEC_MDot));
1274:   PetscFunctionReturn(PETSC_SUCCESS);
1275: }

1277: PetscErrorCode VecMAXPYAsync_Private(Vec y, PetscInt nv, const PetscScalar alpha[], Vec x[], PetscDeviceContext dctx)
1278: {
1279:   PetscFunctionBegin;
1281:   VecCheckAssembled(y);
1283:   PetscCall(VecSetErrorIfLocked(y, 1));
1284:   PetscCheck(nv >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Number of vectors (given %" PetscInt_FMT ") cannot be negative", nv);
1285:   if (nv) {
1286:     PetscInt zeros = 0;

1288:     PetscAssertPointer(alpha, 3);
1289:     PetscAssertPointer(x, 4);
1290:     for (PetscInt i = 0; i < nv; ++i) {
1294:       PetscCheckSameTypeAndComm(y, 1, x[i], 4);
1295:       VecCheckSameSize(y, 1, x[i], 4);
1296:       PetscCheck(y != x[i], PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Array of vectors 'x' cannot contain y, found x[%" PetscInt_FMT "] == y", i);
1297:       VecCheckAssembled(x[i]);
1298:       PetscCall(VecLockReadPush(x[i]));
1299:       zeros += alpha[i] == (PetscScalar)0.0;
1300:     }

1302:     if (zeros < nv) {
1303:       PetscCall(PetscLogEventBegin(VEC_MAXPY, y, *x, 0, 0));
1304:       VecMethodDispatch(y, dctx, VecAsyncFnName(MAXPY), maxpy, (Vec, PetscInt, const PetscScalar[], Vec[], PetscDeviceContext), nv, alpha, x);
1305:       PetscCall(PetscLogEventEnd(VEC_MAXPY, y, *x, 0, 0));
1306:       PetscCall(PetscObjectStateIncrease((PetscObject)y));
1307:     }

1309:     for (PetscInt i = 0; i < nv; ++i) PetscCall(VecLockReadPop(x[i]));
1310:   }
1311:   PetscFunctionReturn(PETSC_SUCCESS);
1312: }

1314: /*@
1315:   VecMAXPY - Computes `y = y + sum alpha[i] x[i]`

1317:   Logically Collective

1319:   Input Parameters:
1320: + nv    - number of scalars and `x` vectors
1321: . alpha - array of scalars
1322: . y     - one vector
1323: - x     - array of vectors

1325:   Level: intermediate

1327:   Notes:
1328:   `y` cannot be any of the `x` vectors

1330:   The implementation may use BLAS 2 operations when the vectors `y` have been obtained with `VecDuplicateVecs()`

1332: .seealso: [](ch_vectors), `Vec`, `VecMAXPBY()`,`VecAYPX()`, `VecWAXPY()`, `VecAXPY()`, `VecAXPBYPCZ()`, `VecAXPBY()`, `VecDuplicateVecs()`
1333: @*/
1334: PetscErrorCode VecMAXPY(Vec y, PetscInt nv, const PetscScalar alpha[], Vec x[])
1335: {
1336:   PetscFunctionBegin;
1337:   PetscCall(VecMAXPYAsync_Private(y, nv, alpha, x, NULL));
1338:   PetscFunctionReturn(PETSC_SUCCESS);
1339: }

1341: /*@
1342:   VecMAXPBY - Computes `y = beta y + sum alpha[i] x[i]`

1344:   Logically Collective

1346:   Input Parameters:
1347: + nv    - number of scalars and `x` vectors
1348: . alpha - array of scalars
1349: . beta  - scalar
1350: . y     - one vector
1351: - x     - array of vectors

1353:   Level: intermediate

1355:   Note:
1356:   `y` cannot be any of the `x` vectors.

1358:   Developer Notes:
1359:   This is a convenience routine, but implementations might be able to optimize it, for example, when `beta` is zero.

1361: .seealso: [](ch_vectors), `Vec`, `VecMAXPY()`, `VecAYPX()`, `VecWAXPY()`, `VecAXPY()`, `VecAXPBYPCZ()`, `VecAXPBY()`
1362: @*/
1363: PetscErrorCode VecMAXPBY(Vec y, PetscInt nv, const PetscScalar alpha[], PetscScalar beta, Vec x[])
1364: {
1365:   PetscFunctionBegin;
1367:   VecCheckAssembled(y);
1369:   PetscCall(VecSetErrorIfLocked(y, 1));
1370:   PetscCheck(nv >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Number of vectors (given %" PetscInt_FMT ") cannot be negative", nv);

1373:   if (y->ops->maxpby) {
1374:     PetscInt zeros = 0;

1376:     if (nv) {
1377:       PetscAssertPointer(alpha, 3);
1378:       PetscAssertPointer(x, 5);
1379:     }

1381:     for (PetscInt i = 0; i < nv; ++i) { // scan all alpha[]
1385:       PetscCheckSameTypeAndComm(y, 1, x[i], 5);
1386:       VecCheckSameSize(y, 1, x[i], 5);
1387:       PetscCheck(y != x[i], PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Array of vectors 'x' cannot contain y, found x[%" PetscInt_FMT "] == y", i);
1388:       VecCheckAssembled(x[i]);
1389:       PetscCall(VecLockReadPush(x[i]));
1390:       zeros += alpha[i] == (PetscScalar)0.0;
1391:     }

1393:     if (zeros < nv) { // has nonzero alpha
1394:       PetscCall(PetscLogEventBegin(VEC_MAXPY, y, *x, 0, 0));
1395:       PetscUseTypeMethod(y, maxpby, nv, alpha, beta, x);
1396:       PetscCall(PetscLogEventEnd(VEC_MAXPY, y, *x, 0, 0));
1397:       PetscCall(PetscObjectStateIncrease((PetscObject)y));
1398:     } else {
1399:       PetscCall(VecScale(y, beta));
1400:     }

1402:     for (PetscInt i = 0; i < nv; ++i) PetscCall(VecLockReadPop(x[i]));
1403:   } else { // no maxpby
1404:     if (beta == 0.0) PetscCall(VecSet(y, 0.0));
1405:     else PetscCall(VecScale(y, beta));
1406:     PetscCall(VecMAXPY(y, nv, alpha, x));
1407:   }
1408:   PetscFunctionReturn(PETSC_SUCCESS);
1409: }

1411: /*@
1412:   VecConcatenate - Creates a new vector that is a vertical concatenation of all the given array of vectors
1413:   in the order they appear in the array. The concatenated vector resides on the same
1414:   communicator and is the same type as the source vectors.

1416:   Collective

1418:   Input Parameters:
1419: + nx - number of vectors to be concatenated
1420: - X  - array containing the vectors to be concatenated in the order of concatenation

1422:   Output Parameters:
1423: + Y    - concatenated vector
1424: - x_is - array of index sets corresponding to the concatenated components of `Y` (pass `NULL` if not needed)

1426:   Level: advanced

1428:   Notes:
1429:   Concatenation is similar to the functionality of a `VECNEST` object; they both represent combination of
1430:   different vector spaces. However, concatenated vectors do not store any information about their
1431:   sub-vectors and own their own data. Consequently, this function provides index sets to enable the
1432:   manipulation of data in the concatenated vector that corresponds to the original components at creation.

1434:   This is a useful tool for outer loop algorithms, particularly constrained optimizers, where the solver
1435:   has to operate on combined vector spaces and cannot utilize `VECNEST` objects due to incompatibility with
1436:   bound projections.

1438: .seealso: [](ch_vectors), `Vec`, `VECNEST`, `VECSCATTER`, `VecScatterCreate()`
1439: @*/
1440: PetscErrorCode VecConcatenate(PetscInt nx, const Vec X[], Vec *Y, IS *x_is[])
1441: {
1442:   MPI_Comm comm;
1443:   VecType  vec_type;
1444:   Vec      Ytmp, Xtmp;
1445:   IS      *is_tmp;
1446:   PetscInt i, shift = 0, Xnl, Xng, Xbegin;

1448:   PetscFunctionBegin;
1452:   PetscAssertPointer(Y, 3);

1454:   if ((*X)->ops->concatenate) {
1455:     /* use the dedicated concatenation function if available */
1456:     PetscCall((*(*X)->ops->concatenate)(nx, X, Y, x_is));
1457:   } else {
1458:     /* loop over vectors and start creating IS */
1459:     comm = PetscObjectComm((PetscObject)*X);
1460:     PetscCall(VecGetType(*X, &vec_type));
1461:     PetscCall(PetscMalloc1(nx, &is_tmp));
1462:     for (i = 0; i < nx; i++) {
1463:       PetscCall(VecGetSize(X[i], &Xng));
1464:       PetscCall(VecGetLocalSize(X[i], &Xnl));
1465:       PetscCall(VecGetOwnershipRange(X[i], &Xbegin, NULL));
1466:       PetscCall(ISCreateStride(comm, Xnl, shift + Xbegin, 1, &is_tmp[i]));
1467:       shift += Xng;
1468:     }
1469:     /* create the concatenated vector */
1470:     PetscCall(VecCreate(comm, &Ytmp));
1471:     PetscCall(VecSetType(Ytmp, vec_type));
1472:     PetscCall(VecSetSizes(Ytmp, PETSC_DECIDE, shift));
1473:     PetscCall(VecSetUp(Ytmp));
1474:     /* copy data from X array to Y and return */
1475:     for (i = 0; i < nx; i++) {
1476:       PetscCall(VecGetSubVector(Ytmp, is_tmp[i], &Xtmp));
1477:       PetscCall(VecCopy(X[i], Xtmp));
1478:       PetscCall(VecRestoreSubVector(Ytmp, is_tmp[i], &Xtmp));
1479:     }
1480:     *Y = Ytmp;
1481:     if (x_is) {
1482:       *x_is = is_tmp;
1483:     } else {
1484:       for (i = 0; i < nx; i++) PetscCall(ISDestroy(&is_tmp[i]));
1485:       PetscCall(PetscFree(is_tmp));
1486:     }
1487:   }
1488:   PetscFunctionReturn(PETSC_SUCCESS);
1489: }

1491: /* A helper function for VecGetSubVector to check if we can implement it with no-copy (i.e. the subvector shares
1492:    memory with the original vector), and the block size of the subvector.

1494:     Input Parameters:
1495: +   X - the original vector
1496: -   is - the index set of the subvector

1498:     Output Parameters:
1499: +   contig - PETSC_TRUE if the index set refers to contiguous entries on this process, else PETSC_FALSE
1500: .   start  - start of contiguous block, as an offset from the start of the ownership range of the original vector
1501: -   blocksize - the block size of the subvector

1503: */
1504: PetscErrorCode VecGetSubVectorContiguityAndBS_Private(Vec X, IS is, PetscBool *contig, PetscInt *start, PetscInt *blocksize)
1505: {
1506:   PetscInt  gstart, gend, lstart;
1507:   PetscBool red[2] = {PETSC_TRUE /*contiguous*/, PETSC_TRUE /*validVBS*/};
1508:   PetscInt  n, N, ibs, vbs, bs = 1;

1510:   PetscFunctionBegin;
1511:   PetscCall(ISGetLocalSize(is, &n));
1512:   PetscCall(ISGetSize(is, &N));
1513:   PetscCall(ISGetBlockSize(is, &ibs));
1514:   PetscCall(VecGetBlockSize(X, &vbs));
1515:   PetscCall(VecGetOwnershipRange(X, &gstart, &gend));
1516:   PetscCall(ISContiguousLocal(is, gstart, gend, &lstart, &red[0]));
1517:   /* block size is given by IS if ibs > 1; otherwise, check the vector */
1518:   if (ibs > 1) {
1519:     PetscCallMPI(MPIU_Allreduce(MPI_IN_PLACE, red, 1, MPIU_BOOL, MPI_LAND, PetscObjectComm((PetscObject)is)));
1520:     bs = ibs;
1521:   } else {
1522:     if (n % vbs || vbs == 1) red[1] = PETSC_FALSE; /* this process invalidate the collectiveness of block size */
1523:     PetscCallMPI(MPIU_Allreduce(MPI_IN_PLACE, red, 2, MPIU_BOOL, MPI_LAND, PetscObjectComm((PetscObject)is)));
1524:     if (red[0] && red[1]) bs = vbs; /* all processes have a valid block size and the access will be contiguous */
1525:   }

1527:   *contig    = red[0];
1528:   *start     = lstart;
1529:   *blocksize = bs;
1530:   PetscFunctionReturn(PETSC_SUCCESS);
1531: }

1533: /* A helper function for VecGetSubVector, to be used when we have to build a standalone subvector through VecScatter

1535:     Input Parameters:
1536: +   X - the original vector
1537: .   is - the index set of the subvector
1538: -   bs - the block size of the subvector, gotten from VecGetSubVectorContiguityAndBS_Private()

1540:     Output Parameter:
1541: .   Z  - the subvector, which will compose the VecScatter context on output
1542: */
1543: PetscErrorCode VecGetSubVectorThroughVecScatter_Private(Vec X, IS is, PetscInt bs, Vec *Z)
1544: {
1545:   PetscInt   n, N;
1546:   VecScatter vscat;
1547:   Vec        Y;

1549:   PetscFunctionBegin;
1550:   PetscCall(ISGetLocalSize(is, &n));
1551:   PetscCall(ISGetSize(is, &N));
1552:   PetscCall(VecCreate(PetscObjectComm((PetscObject)is), &Y));
1553:   PetscCall(VecSetSizes(Y, n, N));
1554:   PetscCall(VecSetBlockSize(Y, bs));
1555:   PetscCall(VecSetType(Y, ((PetscObject)X)->type_name));
1556:   PetscCall(VecScatterCreate(X, is, Y, NULL, &vscat));
1557:   PetscCall(VecScatterBegin(vscat, X, Y, INSERT_VALUES, SCATTER_FORWARD));
1558:   PetscCall(VecScatterEnd(vscat, X, Y, INSERT_VALUES, SCATTER_FORWARD));
1559:   PetscCall(PetscObjectCompose((PetscObject)Y, "VecGetSubVector_Scatter", (PetscObject)vscat));
1560:   PetscCall(VecScatterDestroy(&vscat));
1561:   *Z = Y;
1562:   PetscFunctionReturn(PETSC_SUCCESS);
1563: }

1565: /*@
1566:   VecGetSubVector - Gets a vector representing part of another vector

1568:   Collective

1570:   Input Parameters:
1571: + X  - vector from which to extract a subvector
1572: - is - index set representing portion of `X` to extract

1574:   Output Parameter:
1575: . Y - subvector corresponding to `is`

1577:   Level: advanced

1579:   Notes:
1580:   The subvector `Y` should be returned with `VecRestoreSubVector()`.
1581:   `X` and `is` must be defined on the same communicator

1583:   Changes to the subvector will be reflected in the `X` vector on the call to `VecRestoreSubVector()`.

1585:   This function may return a subvector without making a copy, therefore it is not safe to use the original vector while
1586:   modifying the subvector.  Other non-overlapping subvectors can still be obtained from `X` using this function.

1588:   The resulting subvector inherits the block size from `is` if greater than one. Otherwise, the block size is guessed from the block size of the original `X`.

1590: .seealso: [](ch_vectors), `Vec`, `IS`, `VECNEST`, `MatCreateSubMatrix()`
1591: @*/
1592: PetscErrorCode VecGetSubVector(Vec X, IS is, Vec *Y)
1593: {
1594:   Vec Z;

1596:   PetscFunctionBegin;
1599:   PetscCheckSameComm(X, 1, is, 2);
1600:   PetscAssertPointer(Y, 3);
1601:   if (X->ops->getsubvector) {
1602:     PetscUseTypeMethod(X, getsubvector, is, &Z);
1603:   } else { /* Default implementation currently does no caching */
1604:     PetscBool contig;
1605:     PetscInt  n, N, start, bs;

1607:     PetscCall(ISGetLocalSize(is, &n));
1608:     PetscCall(ISGetSize(is, &N));
1609:     PetscCall(VecGetSubVectorContiguityAndBS_Private(X, is, &contig, &start, &bs));
1610:     if (contig) { /* We can do a no-copy implementation */
1611:       const PetscScalar *x;
1612:       PetscInt           state = 0;
1613:       PetscBool          isstd, iscuda, iship;

1615:       PetscCall(PetscObjectTypeCompareAny((PetscObject)X, &isstd, VECSEQ, VECMPI, VECSTANDARD, ""));
1616:       PetscCall(PetscObjectTypeCompareAny((PetscObject)X, &iscuda, VECSEQCUDA, VECMPICUDA, ""));
1617:       PetscCall(PetscObjectTypeCompareAny((PetscObject)X, &iship, VECSEQHIP, VECMPIHIP, ""));
1618:       if (iscuda) {
1619: #if defined(PETSC_HAVE_CUDA)
1620:         const PetscScalar *x_d;
1621:         PetscMPIInt        size;
1622:         PetscOffloadMask   flg;

1624:         PetscCall(VecCUDAGetArrays_Private(X, &x, &x_d, &flg));
1625:         PetscCheck(flg != PETSC_OFFLOAD_UNALLOCATED, PETSC_COMM_SELF, PETSC_ERR_SUP, "Not for PETSC_OFFLOAD_UNALLOCATED");
1626:         PetscCheck(!n || x || x_d, PETSC_COMM_SELF, PETSC_ERR_SUP, "Missing vector data");
1627:         if (x) x += start;
1628:         if (x_d) x_d += start;
1629:         PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)X), &size));
1630:         if (size == 1) {
1631:           PetscCall(VecCreateSeqCUDAWithArrays(PetscObjectComm((PetscObject)X), bs, n, x, x_d, &Z));
1632:         } else {
1633:           PetscCall(VecCreateMPICUDAWithArrays(PetscObjectComm((PetscObject)X), bs, n, N, x, x_d, &Z));
1634:         }
1635:         Z->offloadmask = flg;
1636: #endif
1637:       } else if (iship) {
1638: #if defined(PETSC_HAVE_HIP)
1639:         const PetscScalar *x_d;
1640:         PetscMPIInt        size;
1641:         PetscOffloadMask   flg;

1643:         PetscCall(VecHIPGetArrays_Private(X, &x, &x_d, &flg));
1644:         PetscCheck(flg != PETSC_OFFLOAD_UNALLOCATED, PETSC_COMM_SELF, PETSC_ERR_SUP, "Not for PETSC_OFFLOAD_UNALLOCATED");
1645:         PetscCheck(!n || x || x_d, PETSC_COMM_SELF, PETSC_ERR_SUP, "Missing vector data");
1646:         if (x) x += start;
1647:         if (x_d) x_d += start;
1648:         PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)X), &size));
1649:         if (size == 1) {
1650:           PetscCall(VecCreateSeqHIPWithArrays(PetscObjectComm((PetscObject)X), bs, n, x, x_d, &Z));
1651:         } else {
1652:           PetscCall(VecCreateMPIHIPWithArrays(PetscObjectComm((PetscObject)X), bs, n, N, x, x_d, &Z));
1653:         }
1654:         Z->offloadmask = flg;
1655: #endif
1656:       } else if (isstd) {
1657:         PetscMPIInt size;

1659:         PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)X), &size));
1660:         PetscCall(VecGetArrayRead(X, &x));
1661:         if (x) x += start;
1662:         if (size == 1) {
1663:           PetscCall(VecCreateSeqWithArray(PetscObjectComm((PetscObject)X), bs, n, x, &Z));
1664:         } else {
1665:           PetscCall(VecCreateMPIWithArray(PetscObjectComm((PetscObject)X), bs, n, N, x, &Z));
1666:         }
1667:         PetscCall(VecRestoreArrayRead(X, &x));
1668:       } else { /* default implementation: use place array */
1669:         PetscCall(VecGetArrayRead(X, &x));
1670:         PetscCall(VecCreate(PetscObjectComm((PetscObject)X), &Z));
1671:         PetscCall(VecSetType(Z, ((PetscObject)X)->type_name));
1672:         PetscCall(VecSetSizes(Z, n, N));
1673:         PetscCall(VecSetBlockSize(Z, bs));
1674:         PetscCall(VecPlaceArray(Z, PetscSafePointerPlusOffset(x, start)));
1675:         PetscCall(VecRestoreArrayRead(X, &x));
1676:       }

1678:       /* this is relevant only in debug mode */
1679:       PetscCall(VecLockGet(X, &state));
1680:       if (state) PetscCall(VecLockReadPush(Z));
1681:       Z->ops->placearray   = NULL;
1682:       Z->ops->replacearray = NULL;
1683:     } else { /* Have to create a scatter and do a copy */
1684:       PetscCall(VecGetSubVectorThroughVecScatter_Private(X, is, bs, &Z));
1685:     }
1686:   }
1687:   /* Record the state when the subvector was gotten so we know whether its values need to be put back */
1688:   if (VecGetSubVectorSavedStateId < 0) PetscCall(PetscObjectComposedDataRegister(&VecGetSubVectorSavedStateId));
1689:   PetscCall(PetscObjectComposedDataSetInt((PetscObject)Z, VecGetSubVectorSavedStateId, 1));
1690:   *Y = Z;
1691:   PetscFunctionReturn(PETSC_SUCCESS);
1692: }

1694: /*@
1695:   VecRestoreSubVector - Restores a subvector extracted using `VecGetSubVector()`

1697:   Collective

1699:   Input Parameters:
1700: + X  - vector from which subvector was obtained
1701: . is - index set representing the subset of `X`
1702: - Y  - subvector being restored

1704:   Level: advanced

1706: .seealso: [](ch_vectors), `Vec`, `IS`, `VecGetSubVector()`
1707: @*/
1708: PetscErrorCode VecRestoreSubVector(Vec X, IS is, Vec *Y)
1709: {
1710:   PETSC_UNUSED PetscObjectState dummystate = 0;
1711:   PetscBool                     unchanged;

1713:   PetscFunctionBegin;
1716:   PetscCheckSameComm(X, 1, is, 2);
1717:   PetscAssertPointer(Y, 3);

1720:   if (X->ops->restoresubvector) PetscUseTypeMethod(X, restoresubvector, is, Y);
1721:   else {
1722:     PetscCall(PetscObjectComposedDataGetInt((PetscObject)*Y, VecGetSubVectorSavedStateId, dummystate, unchanged));
1723:     if (!unchanged) { /* If Y's state has not changed since VecGetSubVector(), we only need to destroy Y */
1724:       VecScatter scatter;
1725:       PetscInt   state;

1727:       PetscCall(VecLockGet(X, &state));
1728:       PetscCheck(state == 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vec X is locked for read-only or read/write access");

1730:       PetscCall(PetscObjectQuery((PetscObject)*Y, "VecGetSubVector_Scatter", (PetscObject *)&scatter));
1731:       if (scatter) {
1732:         PetscCall(VecScatterBegin(scatter, *Y, X, INSERT_VALUES, SCATTER_REVERSE));
1733:         PetscCall(VecScatterEnd(scatter, *Y, X, INSERT_VALUES, SCATTER_REVERSE));
1734:       } else {
1735:         PetscBool iscuda, iship;
1736:         PetscCall(PetscObjectTypeCompareAny((PetscObject)X, &iscuda, VECSEQCUDA, VECMPICUDA, ""));
1737:         PetscCall(PetscObjectTypeCompareAny((PetscObject)X, &iship, VECSEQHIP, VECMPIHIP, ""));

1739:         if (iscuda) {
1740: #if defined(PETSC_HAVE_CUDA)
1741:           PetscOffloadMask ymask = (*Y)->offloadmask;

1743:           /* The offloadmask of X dictates where to move memory
1744:               If X GPU data is valid, then move Y data on GPU if needed
1745:               Otherwise, move back to the CPU */
1746:           switch (X->offloadmask) {
1747:           case PETSC_OFFLOAD_BOTH:
1748:             if (ymask == PETSC_OFFLOAD_CPU) {
1749:               PetscCall(VecCUDAResetArray(*Y));
1750:             } else if (ymask == PETSC_OFFLOAD_GPU) {
1751:               X->offloadmask = PETSC_OFFLOAD_GPU;
1752:             }
1753:             break;
1754:           case PETSC_OFFLOAD_GPU:
1755:             if (ymask == PETSC_OFFLOAD_CPU) PetscCall(VecCUDAResetArray(*Y));
1756:             break;
1757:           case PETSC_OFFLOAD_CPU:
1758:             if (ymask == PETSC_OFFLOAD_GPU) PetscCall(VecResetArray(*Y));
1759:             break;
1760:           case PETSC_OFFLOAD_UNALLOCATED:
1761:           case PETSC_OFFLOAD_KOKKOS:
1762:             SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB, "This should not happen");
1763:           }
1764: #endif
1765:         } else if (iship) {
1766: #if defined(PETSC_HAVE_HIP)
1767:           PetscOffloadMask ymask = (*Y)->offloadmask;

1769:           /* The offloadmask of X dictates where to move memory
1770:               If X GPU data is valid, then move Y data on GPU if needed
1771:               Otherwise, move back to the CPU */
1772:           switch (X->offloadmask) {
1773:           case PETSC_OFFLOAD_BOTH:
1774:             if (ymask == PETSC_OFFLOAD_CPU) {
1775:               PetscCall(VecHIPResetArray(*Y));
1776:             } else if (ymask == PETSC_OFFLOAD_GPU) {
1777:               X->offloadmask = PETSC_OFFLOAD_GPU;
1778:             }
1779:             break;
1780:           case PETSC_OFFLOAD_GPU:
1781:             if (ymask == PETSC_OFFLOAD_CPU) PetscCall(VecHIPResetArray(*Y));
1782:             break;
1783:           case PETSC_OFFLOAD_CPU:
1784:             if (ymask == PETSC_OFFLOAD_GPU) PetscCall(VecResetArray(*Y));
1785:             break;
1786:           case PETSC_OFFLOAD_UNALLOCATED:
1787:           case PETSC_OFFLOAD_KOKKOS:
1788:             SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB, "This should not happen");
1789:           }
1790: #endif
1791:         } else {
1792:           /* If OpenCL vecs updated the device memory, this triggers a copy on the CPU */
1793:           PetscCall(VecResetArray(*Y));
1794:         }
1795:         PetscCall(PetscObjectStateIncrease((PetscObject)X));
1796:       }
1797:     }
1798:   }
1799:   PetscCall(VecDestroy(Y));
1800:   PetscFunctionReturn(PETSC_SUCCESS);
1801: }

1803: /*@
1804:   VecCreateLocalVector - Creates a vector object suitable for use with `VecGetLocalVector()` and friends. You must call `VecDestroy()` when the
1805:   vector is no longer needed.

1807:   Not Collective.

1809:   Input Parameter:
1810: . v - The vector for which the local vector is desired.

1812:   Output Parameter:
1813: . w - Upon exit this contains the local vector.

1815:   Level: beginner

1817: .seealso: [](ch_vectors), `Vec`, `VecGetLocalVectorRead()`, `VecRestoreLocalVectorRead()`, `VecGetLocalVector()`, `VecRestoreLocalVector()`
1818: @*/
1819: PetscErrorCode VecCreateLocalVector(Vec v, Vec *w)
1820: {
1821:   VecType  roottype;
1822:   PetscInt n;

1824:   PetscFunctionBegin;
1826:   PetscAssertPointer(w, 2);
1827:   if (v->ops->createlocalvector) {
1828:     PetscUseTypeMethod(v, createlocalvector, w);
1829:     PetscFunctionReturn(PETSC_SUCCESS);
1830:   }
1831:   PetscCall(VecGetRootType_Private(v, &roottype));
1832:   PetscCall(VecCreate(PETSC_COMM_SELF, w));
1833:   PetscCall(VecGetLocalSize(v, &n));
1834:   PetscCall(VecSetSizes(*w, n, n));
1835:   PetscCall(VecGetBlockSize(v, &n));
1836:   PetscCall(VecSetBlockSize(*w, n));
1837:   PetscCall(VecSetType(*w, roottype));
1838:   PetscFunctionReturn(PETSC_SUCCESS);
1839: }

1841: /*@
1842:   VecGetLocalVectorRead - Maps the local portion of a vector into a
1843:   vector.

1845:   Not Collective.

1847:   Input Parameter:
1848: . v - The vector for which the local vector is desired.

1850:   Output Parameter:
1851: . w - Upon exit this contains the local vector.

1853:   Level: beginner

1855:   Notes:
1856:   You must call `VecRestoreLocalVectorRead()` when the local
1857:   vector is no longer needed.

1859:   This function is similar to `VecGetArrayRead()` which maps the local
1860:   portion into a raw pointer.  `VecGetLocalVectorRead()` is usually
1861:   almost as efficient as `VecGetArrayRead()` but in certain circumstances
1862:   `VecGetLocalVectorRead()` can be much more efficient than
1863:   `VecGetArrayRead()`.  This is because the construction of a contiguous
1864:   array representing the vector data required by `VecGetArrayRead()` can
1865:   be an expensive operation for certain vector types.  For example, for
1866:   GPU vectors `VecGetArrayRead()` requires that the data between device
1867:   and host is synchronized.

1869:   Unlike `VecGetLocalVector()`, this routine is not collective and
1870:   preserves cached information.

1872: .seealso: [](ch_vectors), `Vec`, `VecCreateLocalVector()`, `VecRestoreLocalVectorRead()`, `VecGetLocalVector()`, `VecGetArrayRead()`, `VecGetArray()`
1873: @*/
1874: PetscErrorCode VecGetLocalVectorRead(Vec v, Vec w)
1875: {
1876:   PetscFunctionBegin;
1879:   VecCheckSameLocalSize(v, 1, w, 2);
1880:   if (v->ops->getlocalvectorread) {
1881:     PetscUseTypeMethod(v, getlocalvectorread, w);
1882:   } else {
1883:     PetscScalar *a;

1885:     PetscCall(VecGetArrayRead(v, (const PetscScalar **)&a));
1886:     PetscCall(VecPlaceArray(w, a));
1887:   }
1888:   PetscCall(PetscObjectStateIncrease((PetscObject)w));
1889:   PetscCall(VecLockReadPush(v));
1890:   PetscCall(VecLockReadPush(w));
1891:   PetscFunctionReturn(PETSC_SUCCESS);
1892: }

1894: /*@
1895:   VecRestoreLocalVectorRead - Unmaps the local portion of a vector
1896:   previously mapped into a vector using `VecGetLocalVectorRead()`.

1898:   Not Collective.

1900:   Input Parameters:
1901: + v - The local portion of this vector was previously mapped into `w` using `VecGetLocalVectorRead()`.
1902: - w - The vector into which the local portion of `v` was mapped.

1904:   Level: beginner

1906: .seealso: [](ch_vectors), `Vec`, `VecCreateLocalVector()`, `VecGetLocalVectorRead()`, `VecGetLocalVector()`, `VecGetArrayRead()`, `VecGetArray()`
1907: @*/
1908: PetscErrorCode VecRestoreLocalVectorRead(Vec v, Vec w)
1909: {
1910:   PetscFunctionBegin;
1913:   if (v->ops->restorelocalvectorread) {
1914:     PetscUseTypeMethod(v, restorelocalvectorread, w);
1915:   } else {
1916:     const PetscScalar *a;

1918:     PetscCall(VecGetArrayRead(w, &a));
1919:     PetscCall(VecRestoreArrayRead(v, &a));
1920:     PetscCall(VecResetArray(w));
1921:   }
1922:   PetscCall(VecLockReadPop(v));
1923:   PetscCall(VecLockReadPop(w));
1924:   PetscCall(PetscObjectStateIncrease((PetscObject)w));
1925:   PetscFunctionReturn(PETSC_SUCCESS);
1926: }

1928: /*@
1929:   VecGetLocalVector - Maps the local portion of a vector into a
1930:   vector.

1932:   Collective

1934:   Input Parameter:
1935: . v - The vector for which the local vector is desired.

1937:   Output Parameter:
1938: . w - Upon exit this contains the local vector.

1940:   Level: beginner

1942:   Notes:
1943:   You must call `VecRestoreLocalVector()` when the local
1944:   vector is no longer needed.

1946:   This function is similar to `VecGetArray()` which maps the local
1947:   portion into a raw pointer.  `VecGetLocalVector()` is usually about as
1948:   efficient as `VecGetArray()` but in certain circumstances
1949:   `VecGetLocalVector()` can be much more efficient than `VecGetArray()`.
1950:   This is because the construction of a contiguous array representing
1951:   the vector data required by `VecGetArray()` can be an expensive
1952:   operation for certain vector types.  For example, for GPU vectors
1953:   `VecGetArray()` requires that the data between device and host is
1954:   synchronized.

1956: .seealso: [](ch_vectors), `Vec`, `VecCreateLocalVector()`, `VecRestoreLocalVector()`, `VecGetLocalVectorRead()`, `VecGetArrayRead()`, `VecGetArray()`
1957: @*/
1958: PetscErrorCode VecGetLocalVector(Vec v, Vec w)
1959: {
1960:   PetscFunctionBegin;
1963:   VecCheckSameLocalSize(v, 1, w, 2);
1964:   if (v->ops->getlocalvector) {
1965:     PetscUseTypeMethod(v, getlocalvector, w);
1966:   } else {
1967:     PetscScalar *a;

1969:     PetscCall(VecGetArray(v, &a));
1970:     PetscCall(VecPlaceArray(w, a));
1971:   }
1972:   PetscCall(PetscObjectStateIncrease((PetscObject)w));
1973:   PetscFunctionReturn(PETSC_SUCCESS);
1974: }

1976: /*@
1977:   VecRestoreLocalVector - Unmaps the local portion of a vector
1978:   previously mapped into a vector using `VecGetLocalVector()`.

1980:   Logically Collective.

1982:   Input Parameters:
1983: + v - The local portion of this vector was previously mapped into `w` using `VecGetLocalVector()`.
1984: - w - The vector into which the local portion of `v` was mapped.

1986:   Level: beginner

1988: .seealso: [](ch_vectors), `Vec`, `VecCreateLocalVector()`, `VecGetLocalVector()`, `VecGetLocalVectorRead()`, `VecRestoreLocalVectorRead()`, `LocalVectorRead()`, `VecGetArrayRead()`, `VecGetArray()`
1989: @*/
1990: PetscErrorCode VecRestoreLocalVector(Vec v, Vec w)
1991: {
1992:   PetscFunctionBegin;
1995:   if (v->ops->restorelocalvector) {
1996:     PetscUseTypeMethod(v, restorelocalvector, w);
1997:   } else {
1998:     PetscScalar *a;
1999:     PetscCall(VecGetArray(w, &a));
2000:     PetscCall(VecRestoreArray(v, &a));
2001:     PetscCall(VecResetArray(w));
2002:   }
2003:   PetscCall(PetscObjectStateIncrease((PetscObject)w));
2004:   PetscCall(PetscObjectStateIncrease((PetscObject)v));
2005:   PetscFunctionReturn(PETSC_SUCCESS);
2006: }

2008: /*@C
2009:   VecGetArray - Returns a pointer to a contiguous array that contains this
2010:   MPI processes's portion of the vector data

2012:   Logically Collective

2014:   Input Parameter:
2015: . x - the vector

2017:   Output Parameter:
2018: . a - location to put pointer to the array

2020:   Level: beginner

2022:   Notes:
2023:   For the standard PETSc vectors, `VecGetArray()` returns a pointer to the local data array and
2024:   does not use any copies. If the underlying vector data is not stored in a contiguous array
2025:   this routine will copy the data to a contiguous array and return a pointer to that. You MUST
2026:   call `VecRestoreArray()` when you no longer need access to the array.

2028:   For vectors that may also have the array data in GPU memory, for example, `VECCUDA`, this call ensures the CPU array has the
2029:   most recent array values by copying the data from the GPU memory if needed.

2031:   Fortran Note:
2032: .vb
2033:   PetscScalar, pointer :: a(:)
2034: .ve

2036: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecGetArrays()`, `VecPlaceArray()`, `VecGetArray2d()`,
2037:           `VecGetArrayPair()`, `VecRestoreArrayPair()`, `VecGetArrayWrite()`, `VecRestoreArrayWrite()`, `VecGetArrayAndMemType()`
2038: @*/
2039: PetscErrorCode VecGetArray(Vec x, PetscScalar *a[])
2040: {
2041:   PetscFunctionBegin;
2043:   PetscCall(VecSetErrorIfLocked(x, 1));
2044:   if (x->ops->getarray) { /* The if-else order matters! VECNEST, VECCUDA etc should have ops->getarray while VECCUDA etc are petscnative */
2045:     PetscUseTypeMethod(x, getarray, a);
2046:   } else if (x->petscnative) { /* VECSTANDARD */
2047:     *a = *((PetscScalar **)x->data);
2048:   } else SETERRQ(PetscObjectComm((PetscObject)x), PETSC_ERR_SUP, "Cannot get array for vector type \"%s\"", ((PetscObject)x)->type_name);
2049:   PetscFunctionReturn(PETSC_SUCCESS);
2050: }

2052: /*@C
2053:   VecRestoreArray - Restores a vector after `VecGetArray()` has been called and the array is no longer needed

2055:   Logically Collective

2057:   Input Parameters:
2058: + x - the vector
2059: - a - location of pointer to array obtained from `VecGetArray()`

2061:   Level: beginner

2063: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArrayRead()`, `VecRestoreArrays()`, `VecPlaceArray()`, `VecRestoreArray2d()`,
2064:           `VecGetArrayPair()`, `VecRestoreArrayPair()`
2065: @*/
2066: PetscErrorCode VecRestoreArray(Vec x, PetscScalar *a[])
2067: {
2068:   PetscFunctionBegin;
2070:   if (a) PetscAssertPointer(a, 2);
2071:   if (x->ops->restorearray) {
2072:     PetscUseTypeMethod(x, restorearray, a);
2073:   } else PetscCheck(x->petscnative, PetscObjectComm((PetscObject)x), PETSC_ERR_SUP, "Cannot restore array for vector type \"%s\"", ((PetscObject)x)->type_name);
2074:   if (a) *a = NULL;
2075:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
2076:   PetscFunctionReturn(PETSC_SUCCESS);
2077: }
2078: /*@C
2079:   VecGetArrayRead - Get read-only pointer to contiguous array containing this processor's portion of the vector data.

2081:   Not Collective

2083:   Input Parameter:
2084: . x - the vector

2086:   Output Parameter:
2087: . a - the array

2089:   Level: beginner

2091:   Notes:
2092:   The array must be returned using a matching call to `VecRestoreArrayRead()`.

2094:   Unlike `VecGetArray()`, preserves cached information like vector norms.

2096:   Standard PETSc vectors use contiguous storage so that this routine does not perform a copy.  Other vector
2097:   implementations may require a copy, but such implementations should cache the contiguous representation so that
2098:   only one copy is performed when this routine is called multiple times in sequence.

2100:   For vectors that may also have the array data in GPU memory, for example, `VECCUDA`, this call ensures the CPU array has the
2101:   most recent array values by copying the data from the GPU memory if needed.

2103: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`,
2104:           `VecGetArrayAndMemType()`
2105: @*/
2106: PetscErrorCode VecGetArrayRead(Vec x, const PetscScalar *a[])
2107: {
2108:   PetscFunctionBegin;
2110:   PetscAssertPointer(a, 2);
2111:   if (x->ops->getarrayread) {
2112:     PetscUseTypeMethod(x, getarrayread, a);
2113:   } else if (x->ops->getarray) {
2114:     PetscObjectState state;

2116:     /* VECNEST, VECCUDA, VECKOKKOS etc */
2117:     // x->ops->getarray may bump the object state, but since we know this is a read-only get
2118:     // we can just undo that
2119:     PetscCall(PetscObjectStateGet((PetscObject)x, &state));
2120:     PetscUseTypeMethod(x, getarray, (PetscScalar **)a);
2121:     PetscCall(PetscObjectStateSet((PetscObject)x, state));
2122:   } else if (x->petscnative) {
2123:     /* VECSTANDARD */
2124:     *a = *((PetscScalar **)x->data);
2125:   } else SETERRQ(PetscObjectComm((PetscObject)x), PETSC_ERR_SUP, "Cannot get array read for vector type \"%s\"", ((PetscObject)x)->type_name);
2126:   PetscFunctionReturn(PETSC_SUCCESS);
2127: }

2129: /*@C
2130:   VecRestoreArrayRead - Restore array obtained with `VecGetArrayRead()`

2132:   Not Collective

2134:   Input Parameters:
2135: + x - the vector
2136: - a - the array

2138:   Level: beginner

2140: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`
2141: @*/
2142: PetscErrorCode VecRestoreArrayRead(Vec x, const PetscScalar *a[])
2143: {
2144:   PetscFunctionBegin;
2146:   if (a) PetscAssertPointer(a, 2);
2147:   if (x->petscnative) { /* VECSTANDARD, VECCUDA, VECKOKKOS etc */
2148:     /* nothing */
2149:   } else if (x->ops->restorearrayread) { /* VECNEST */
2150:     PetscUseTypeMethod(x, restorearrayread, a);
2151:   } else { /* No one? */
2152:     PetscObjectState state;

2154:     // x->ops->restorearray may bump the object state, but since we know this is a read-restore
2155:     // we can just undo that
2156:     PetscCall(PetscObjectStateGet((PetscObject)x, &state));
2157:     PetscUseTypeMethod(x, restorearray, (PetscScalar **)a);
2158:     PetscCall(PetscObjectStateSet((PetscObject)x, state));
2159:   }
2160:   if (a) *a = NULL;
2161:   PetscFunctionReturn(PETSC_SUCCESS);
2162: }

2164: /*@C
2165:   VecGetArrayWrite - Returns a pointer to a contiguous array that WILL contain this
2166:   MPI processes's portion of the vector data.

2168:   Logically Collective

2170:   Input Parameter:
2171: . x - the vector

2173:   Output Parameter:
2174: . a - location to put pointer to the array

2176:   Level: intermediate

2178:   Note:
2179:   The values in this array are NOT valid, the caller of this routine is responsible for putting
2180:   values into the array; any values it does not set will be invalid.

2182:   The array must be returned using a matching call to `VecRestoreArrayWrite()`.

2184:   For vectors associated with GPUs, the host and device vectors are not synchronized before
2185:   giving access. If you need correct values in the array use `VecGetArray()`

2187: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecGetArrays()`, `VecPlaceArray()`, `VecGetArray2d()`,
2188:           `VecGetArrayPair()`, `VecRestoreArrayPair()`, `VecGetArray()`, `VecRestoreArrayWrite()`, `VecGetArrayAndMemType()`
2189: @*/
2190: PetscErrorCode VecGetArrayWrite(Vec x, PetscScalar *a[])
2191: {
2192:   PetscFunctionBegin;
2194:   PetscAssertPointer(a, 2);
2195:   PetscCall(VecSetErrorIfLocked(x, 1));
2196:   if (x->ops->getarraywrite) {
2197:     PetscUseTypeMethod(x, getarraywrite, a);
2198:   } else {
2199:     PetscCall(VecGetArray(x, a));
2200:   }
2201:   PetscFunctionReturn(PETSC_SUCCESS);
2202: }

2204: /*@C
2205:   VecRestoreArrayWrite - Restores a vector after `VecGetArrayWrite()` has been called.

2207:   Logically Collective

2209:   Input Parameters:
2210: + x - the vector
2211: - a - location of pointer to array obtained from `VecGetArray()`

2213:   Level: beginner

2215: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArrayRead()`, `VecRestoreArrays()`, `VecPlaceArray()`, `VecRestoreArray2d()`,
2216:           `VecGetArrayPair()`, `VecRestoreArrayPair()`, `VecGetArrayWrite()`
2217: @*/
2218: PetscErrorCode VecRestoreArrayWrite(Vec x, PetscScalar *a[])
2219: {
2220:   PetscFunctionBegin;
2222:   if (a) PetscAssertPointer(a, 2);
2223:   if (x->ops->restorearraywrite) {
2224:     PetscUseTypeMethod(x, restorearraywrite, a);
2225:   } else if (x->ops->restorearray) {
2226:     PetscUseTypeMethod(x, restorearray, a);
2227:   }
2228:   if (a) *a = NULL;
2229:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
2230:   PetscFunctionReturn(PETSC_SUCCESS);
2231: }

2233: /*@C
2234:   VecGetArrays - Returns a pointer to the arrays in a set of vectors
2235:   that were created by a call to `VecDuplicateVecs()`.

2237:   Logically Collective; No Fortran Support

2239:   Input Parameters:
2240: + x - the vectors
2241: - n - the number of vectors

2243:   Output Parameter:
2244: . a - location to put pointer to the array

2246:   Level: intermediate

2248:   Note:
2249:   You MUST call `VecRestoreArrays()` when you no longer need access to the arrays.

2251: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArrays()`
2252: @*/
2253: PetscErrorCode VecGetArrays(const Vec x[], PetscInt n, PetscScalar **a[])
2254: {
2255:   PetscInt      i;
2256:   PetscScalar **q;

2258:   PetscFunctionBegin;
2259:   PetscAssertPointer(x, 1);
2261:   PetscAssertPointer(a, 3);
2262:   PetscCheck(n > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Must get at least one array n = %" PetscInt_FMT, n);
2263:   PetscCall(PetscMalloc1(n, &q));
2264:   for (i = 0; i < n; ++i) PetscCall(VecGetArray(x[i], &q[i]));
2265:   *a = q;
2266:   PetscFunctionReturn(PETSC_SUCCESS);
2267: }

2269: /*@C
2270:   VecRestoreArrays - Restores a group of vectors after `VecGetArrays()`
2271:   has been called.

2273:   Logically Collective; No Fortran Support

2275:   Input Parameters:
2276: + x - the vector
2277: . n - the number of vectors
2278: - a - location of pointer to arrays obtained from `VecGetArrays()`

2280:   Notes:
2281:   For regular PETSc vectors this routine does not involve any copies. For
2282:   any special vectors that do not store local vector data in a contiguous
2283:   array, this routine will copy the data back into the underlying
2284:   vector data structure from the arrays obtained with `VecGetArrays()`.

2286:   Level: intermediate

2288: .seealso: [](ch_vectors), `Vec`, `VecGetArrays()`, `VecRestoreArray()`
2289: @*/
2290: PetscErrorCode VecRestoreArrays(const Vec x[], PetscInt n, PetscScalar **a[])
2291: {
2292:   PetscInt      i;
2293:   PetscScalar **q = *a;

2295:   PetscFunctionBegin;
2296:   PetscAssertPointer(x, 1);
2298:   PetscAssertPointer(a, 3);

2300:   for (i = 0; i < n; ++i) PetscCall(VecRestoreArray(x[i], &q[i]));
2301:   PetscCall(PetscFree(q));
2302:   PetscFunctionReturn(PETSC_SUCCESS);
2303: }

2305: /*@C
2306:   VecGetArrayAndMemType - Like `VecGetArray()`, but if this is a standard device vector (e.g.,
2307:   `VECCUDA`), the returned pointer will be a device pointer to the device memory that contains
2308:   this MPI processes's portion of the vector data.

2310:   Logically Collective; No Fortran Support

2312:   Input Parameter:
2313: . x - the vector

2315:   Output Parameters:
2316: + a     - location to put pointer to the array
2317: - mtype - memory type of the array

2319:   Level: beginner

2321:   Note:
2322:   Device data is guaranteed to have the latest value. Otherwise, when this is a host vector
2323:   (e.g., `VECMPI`), this routine functions the same as `VecGetArray()` and returns a host
2324:   pointer.

2326:   For `VECKOKKOS`, if Kokkos is configured without device (e.g., use serial or openmp), per
2327:   this function, the vector works like `VECSEQ`/`VECMPI`; otherwise, it works like `VECCUDA` or
2328:   `VECHIP` etc.

2330:   Use `VecRestoreArrayAndMemType()` when the array access is no longer needed.

2332: .seealso: [](ch_vectors), `Vec`, `VecRestoreArrayAndMemType()`, `VecGetArrayReadAndMemType()`, `VecGetArrayWriteAndMemType()`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecGetArrays()`,
2333:           `VecPlaceArray()`, `VecGetArray2d()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`, `VecGetArrayWrite()`, `VecRestoreArrayWrite()`
2334: @*/
2335: PetscErrorCode VecGetArrayAndMemType(Vec x, PetscScalar *a[], PetscMemType *mtype)
2336: {
2337:   PetscFunctionBegin;
2340:   PetscAssertPointer(a, 2);
2341:   if (mtype) PetscAssertPointer(mtype, 3);
2342:   PetscCall(VecSetErrorIfLocked(x, 1));
2343:   if (x->ops->getarrayandmemtype) {
2344:     /* VECCUDA, VECKOKKOS etc */
2345:     PetscUseTypeMethod(x, getarrayandmemtype, a, mtype);
2346:   } else {
2347:     /* VECSTANDARD, VECNEST, VECVIENNACL */
2348:     PetscCall(VecGetArray(x, a));
2349:     if (mtype) *mtype = PETSC_MEMTYPE_HOST;
2350:   }
2351:   PetscFunctionReturn(PETSC_SUCCESS);
2352: }

2354: /*@C
2355:   VecRestoreArrayAndMemType - Restores a vector after `VecGetArrayAndMemType()` has been called.

2357:   Logically Collective; No Fortran Support

2359:   Input Parameters:
2360: + x - the vector
2361: - a - location of pointer to array obtained from `VecGetArrayAndMemType()`

2363:   Level: beginner

2365: .seealso: [](ch_vectors), `Vec`, `VecGetArrayAndMemType()`, `VecGetArray()`, `VecRestoreArrayRead()`, `VecRestoreArrays()`,
2366:           `VecPlaceArray()`, `VecRestoreArray2d()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`
2367: @*/
2368: PetscErrorCode VecRestoreArrayAndMemType(Vec x, PetscScalar *a[])
2369: {
2370:   PetscFunctionBegin;
2373:   if (a) PetscAssertPointer(a, 2);
2374:   if (x->ops->restorearrayandmemtype) {
2375:     /* VECCUDA, VECKOKKOS etc */
2376:     PetscUseTypeMethod(x, restorearrayandmemtype, a);
2377:   } else {
2378:     /* VECNEST, VECVIENNACL */
2379:     PetscCall(VecRestoreArray(x, a));
2380:   } /* VECSTANDARD does nothing */
2381:   if (a) *a = NULL;
2382:   PetscCall(PetscObjectStateIncrease((PetscObject)x));
2383:   PetscFunctionReturn(PETSC_SUCCESS);
2384: }

2386: /*@C
2387:   VecGetArrayReadAndMemType - Like `VecGetArrayRead()`, but if the input vector is a device vector, it will return a read-only device pointer.
2388:   The returned pointer is guaranteed to point to up-to-date data. For host vectors, it functions as `VecGetArrayRead()`.

2390:   Not Collective; No Fortran Support

2392:   Input Parameter:
2393: . x - the vector

2395:   Output Parameters:
2396: + a     - the array
2397: - mtype - memory type of the array

2399:   Level: beginner

2401:   Notes:
2402:   The array must be returned using a matching call to `VecRestoreArrayReadAndMemType()`.

2404: .seealso: [](ch_vectors), `Vec`, `VecRestoreArrayReadAndMemType()`, `VecGetArrayAndMemType()`, `VecGetArrayWriteAndMemType()`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`
2405: @*/
2406: PetscErrorCode VecGetArrayReadAndMemType(Vec x, const PetscScalar *a[], PetscMemType *mtype)
2407: {
2408:   PetscFunctionBegin;
2411:   PetscAssertPointer(a, 2);
2412:   if (mtype) PetscAssertPointer(mtype, 3);
2413:   if (x->ops->getarrayreadandmemtype) {
2414:     /* VECCUDA/VECHIP though they are also petscnative */
2415:     PetscUseTypeMethod(x, getarrayreadandmemtype, a, mtype);
2416:   } else if (x->ops->getarrayandmemtype) {
2417:     /* VECKOKKOS */
2418:     PetscObjectState state;

2420:     // see VecGetArrayRead() for why
2421:     PetscCall(PetscObjectStateGet((PetscObject)x, &state));
2422:     PetscUseTypeMethod(x, getarrayandmemtype, (PetscScalar **)a, mtype);
2423:     PetscCall(PetscObjectStateSet((PetscObject)x, state));
2424:   } else {
2425:     PetscCall(VecGetArrayRead(x, a));
2426:     if (mtype) *mtype = PETSC_MEMTYPE_HOST;
2427:   }
2428:   PetscFunctionReturn(PETSC_SUCCESS);
2429: }

2431: /*@C
2432:   VecRestoreArrayReadAndMemType - Restore array obtained with `VecGetArrayReadAndMemType()`

2434:   Not Collective; No Fortran Support

2436:   Input Parameters:
2437: + x - the vector
2438: - a - the array

2440:   Level: beginner

2442: .seealso: [](ch_vectors), `Vec`, `VecGetArrayReadAndMemType()`, `VecRestoreArrayAndMemType()`, `VecRestoreArrayWriteAndMemType()`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`
2443: @*/
2444: PetscErrorCode VecRestoreArrayReadAndMemType(Vec x, const PetscScalar *a[])
2445: {
2446:   PetscFunctionBegin;
2449:   if (a) PetscAssertPointer(a, 2);
2450:   if (x->ops->restorearrayreadandmemtype) {
2451:     /* VECCUDA/VECHIP */
2452:     PetscUseTypeMethod(x, restorearrayreadandmemtype, a);
2453:   } else if (!x->petscnative) {
2454:     /* VECNEST */
2455:     PetscCall(VecRestoreArrayRead(x, a));
2456:   }
2457:   if (a) *a = NULL;
2458:   PetscFunctionReturn(PETSC_SUCCESS);
2459: }

2461: /*@C
2462:   VecGetArrayWriteAndMemType - Like `VecGetArrayWrite()`, but if this is a device vector it will always return
2463:   a device pointer to the device memory that contains this processor's portion of the vector data.

2465:   Logically Collective; No Fortran Support

2467:   Input Parameter:
2468: . x - the vector

2470:   Output Parameters:
2471: + a     - the array
2472: - mtype - memory type of the array

2474:   Level: beginner

2476:   Note:
2477:   The array must be returned using a matching call to `VecRestoreArrayWriteAndMemType()`, where it will label the device memory as most recent.

2479: .seealso: [](ch_vectors), `Vec`, `VecRestoreArrayWriteAndMemType()`, `VecGetArrayReadAndMemType()`, `VecGetArrayAndMemType()`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`,
2480: @*/
2481: PetscErrorCode VecGetArrayWriteAndMemType(Vec x, PetscScalar *a[], PetscMemType *mtype)
2482: {
2483:   PetscFunctionBegin;
2486:   PetscCall(VecSetErrorIfLocked(x, 1));
2487:   PetscAssertPointer(a, 2);
2488:   if (mtype) PetscAssertPointer(mtype, 3);
2489:   if (x->ops->getarraywriteandmemtype) {
2490:     /* VECCUDA, VECHIP, VECKOKKOS etc, though they are also petscnative */
2491:     PetscUseTypeMethod(x, getarraywriteandmemtype, a, mtype);
2492:   } else if (x->ops->getarrayandmemtype) {
2493:     PetscCall(VecGetArrayAndMemType(x, a, mtype));
2494:   } else {
2495:     /* VECNEST, VECVIENNACL */
2496:     PetscCall(VecGetArrayWrite(x, a));
2497:     if (mtype) *mtype = PETSC_MEMTYPE_HOST;
2498:   }
2499:   PetscFunctionReturn(PETSC_SUCCESS);
2500: }

2502: /*@C
2503:   VecRestoreArrayWriteAndMemType - Restore array obtained with `VecGetArrayWriteAndMemType()`

2505:   Logically Collective; No Fortran Support

2507:   Input Parameters:
2508: + x - the vector
2509: - a - the array

2511:   Level: beginner

2513: .seealso: [](ch_vectors), `Vec`, `VecGetArrayWriteAndMemType()`, `VecRestoreArrayAndMemType()`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrayPair()`, `VecRestoreArrayPair()`
2514: @*/
2515: PetscErrorCode VecRestoreArrayWriteAndMemType(Vec x, PetscScalar *a[])
2516: {
2517:   PetscFunctionBegin;
2520:   PetscCall(VecSetErrorIfLocked(x, 1));
2521:   if (a) PetscAssertPointer(a, 2);
2522:   if (x->ops->restorearraywriteandmemtype) {
2523:     /* VECCUDA/VECHIP */
2524:     PetscMemType PETSC_UNUSED mtype; // since this function doesn't accept a memtype?
2525:     PetscUseTypeMethod(x, restorearraywriteandmemtype, a, &mtype);
2526:   } else if (x->ops->restorearrayandmemtype) {
2527:     PetscCall(VecRestoreArrayAndMemType(x, a));
2528:   } else {
2529:     PetscCall(VecRestoreArray(x, a));
2530:   }
2531:   if (a) *a = NULL;
2532:   PetscFunctionReturn(PETSC_SUCCESS);
2533: }

2535: /*@
2536:   VecPlaceArray - Allows one to replace the array in a vector with an
2537:   array provided by the user. This is useful to avoid copying an array
2538:   into a vector.

2540:   Logically Collective; No Fortran Support

2542:   Input Parameters:
2543: + vec   - the vector
2544: - array - the array

2546:   Level: developer

2548:   Notes:
2549:   Adding `const` to `array` was an oversight, as subsequent operations on `vec` would
2550:   likely modify the data in `array`. However, we have kept it to avoid breaking APIs.

2552:   Use `VecReplaceArray()` instead to permanently replace the array

2554:   You can return to the original array with a call to `VecResetArray()`. `vec` does not take
2555:   ownership of `array` in any way.

2557:   The user must free `array` themselves but be careful not to
2558:   do so before the vector has either been destroyed, had its original array restored with
2559:   `VecResetArray()` or permanently replaced with `VecReplaceArray()`.

2561: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecReplaceArray()`, `VecResetArray()`
2562: @*/
2563: PetscErrorCode VecPlaceArray(Vec vec, const PetscScalar array[])
2564: {
2565:   PetscFunctionBegin;
2568:   if (array) PetscAssertPointer(array, 2);
2569:   PetscUseTypeMethod(vec, placearray, array);
2570:   PetscCall(PetscObjectStateIncrease((PetscObject)vec));
2571:   PetscFunctionReturn(PETSC_SUCCESS);
2572: }

2574: /*@C
2575:   VecReplaceArray - Allows one to replace the array in a vector with an
2576:   array provided by the user. This is useful to avoid copying an array
2577:   into a vector.

2579:   Logically Collective; No Fortran Support

2581:   Input Parameters:
2582: + vec   - the vector
2583: - array - the array

2585:   Level: developer

2587:   Notes:
2588:   Adding `const` to `array` was an oversight, as subsequent operations on `vec` would
2589:   likely modify the data in `array`. However, we have kept it to avoid breaking APIs.

2591:   This permanently replaces the array and frees the memory associated
2592:   with the old array. Use `VecPlaceArray()` to temporarily replace the array.

2594:   The memory passed in MUST be obtained with `PetscMalloc()` and CANNOT be
2595:   freed by the user. It will be freed when the vector is destroyed.

2597: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecPlaceArray()`, `VecResetArray()`
2598: @*/
2599: PetscErrorCode VecReplaceArray(Vec vec, const PetscScalar array[])
2600: {
2601:   PetscFunctionBegin;
2604:   PetscUseTypeMethod(vec, replacearray, array);
2605:   PetscCall(PetscObjectStateIncrease((PetscObject)vec));
2606:   PetscFunctionReturn(PETSC_SUCCESS);
2607: }

2609: /*@C
2610:   VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this
2611:   processor's portion of the vector data.  You MUST call `VecRestoreArray2d()`
2612:   when you no longer need access to the array.

2614:   Logically Collective

2616:   Input Parameters:
2617: + x      - the vector
2618: . m      - first dimension of two dimensional array
2619: . n      - second dimension of two dimensional array
2620: . mstart - first index you will use in first coordinate direction (often 0)
2621: - nstart - first index in the second coordinate direction (often 0)

2623:   Output Parameter:
2624: . a - location to put pointer to the array

2626:   Level: developer

2628:   Notes:
2629:   For a vector obtained from `DMCreateLocalVector()` `mstart` and `nstart` are likely
2630:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
2631:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
2632:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray2d()`.

2634:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2636: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
2637:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
2638:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2639: @*/
2640: PetscErrorCode VecGetArray2d(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
2641: {
2642:   PetscInt     i, N;
2643:   PetscScalar *aa;

2645:   PetscFunctionBegin;
2647:   PetscAssertPointer(a, 6);
2649:   PetscCall(VecGetLocalSize(x, &N));
2650:   PetscCheck(m * n == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 2d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n);
2651:   PetscCall(VecGetArray(x, &aa));

2653:   PetscCall(PetscMalloc1(m, a));
2654:   for (i = 0; i < m; i++) (*a)[i] = aa + i * n - nstart;
2655:   *a -= mstart;
2656:   PetscFunctionReturn(PETSC_SUCCESS);
2657: }

2659: /*@C
2660:   VecGetArray2dWrite - Returns a pointer to a 2d contiguous array that will contain this
2661:   processor's portion of the vector data.  You MUST call `VecRestoreArray2dWrite()`
2662:   when you no longer need access to the array.

2664:   Logically Collective

2666:   Input Parameters:
2667: + x      - the vector
2668: . m      - first dimension of two dimensional array
2669: . n      - second dimension of two dimensional array
2670: . mstart - first index you will use in first coordinate direction (often 0)
2671: - nstart - first index in the second coordinate direction (often 0)

2673:   Output Parameter:
2674: . a - location to put pointer to the array

2676:   Level: developer

2678:   Notes:
2679:   For a vector obtained from `DMCreateLocalVector()` `mstart` and `nstart` are likely
2680:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
2681:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
2682:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray2d()`.

2684:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2686: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
2687:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
2688:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2689: @*/
2690: PetscErrorCode VecGetArray2dWrite(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
2691: {
2692:   PetscInt     i, N;
2693:   PetscScalar *aa;

2695:   PetscFunctionBegin;
2697:   PetscAssertPointer(a, 6);
2699:   PetscCall(VecGetLocalSize(x, &N));
2700:   PetscCheck(m * n == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 2d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n);
2701:   PetscCall(VecGetArrayWrite(x, &aa));

2703:   PetscCall(PetscMalloc1(m, a));
2704:   for (i = 0; i < m; i++) (*a)[i] = aa + i * n - nstart;
2705:   *a -= mstart;
2706:   PetscFunctionReturn(PETSC_SUCCESS);
2707: }

2709: /*@C
2710:   VecRestoreArray2d - Restores a vector after `VecGetArray2d()` has been called.

2712:   Logically Collective

2714:   Input Parameters:
2715: + x      - the vector
2716: . m      - first dimension of two dimensional array
2717: . n      - second dimension of the two dimensional array
2718: . mstart - first index you will use in first coordinate direction (often 0)
2719: . nstart - first index in the second coordinate direction (often 0)
2720: - a      - location of pointer to array obtained from `VecGetArray2d()`

2722:   Level: developer

2724:   Notes:
2725:   For regular PETSc vectors this routine does not involve any copies. For
2726:   any special vectors that do not store local vector data in a contiguous
2727:   array, this routine will copy the data back into the underlying
2728:   vector data structure from the array obtained with `VecGetArray()`.

2730:   This routine actually zeros out the `a` pointer.

2732: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
2733:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
2734:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2735: @*/
2736: PetscErrorCode VecRestoreArray2d(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
2737: {
2738:   void *dummy;

2740:   PetscFunctionBegin;
2742:   PetscAssertPointer(a, 6);
2744:   dummy = (void *)(*a + mstart);
2745:   PetscCall(PetscFree(dummy));
2746:   PetscCall(VecRestoreArray(x, NULL));
2747:   *a = NULL;
2748:   PetscFunctionReturn(PETSC_SUCCESS);
2749: }

2751: /*@C
2752:   VecRestoreArray2dWrite - Restores a vector after `VecGetArray2dWrite()` has been called.

2754:   Logically Collective

2756:   Input Parameters:
2757: + x      - the vector
2758: . m      - first dimension of two dimensional array
2759: . n      - second dimension of the two dimensional array
2760: . mstart - first index you will use in first coordinate direction (often 0)
2761: . nstart - first index in the second coordinate direction (often 0)
2762: - a      - location of pointer to array obtained from `VecGetArray2d()`

2764:   Level: developer

2766:   Notes:
2767:   For regular PETSc vectors this routine does not involve any copies. For
2768:   any special vectors that do not store local vector data in a contiguous
2769:   array, this routine will copy the data back into the underlying
2770:   vector data structure from the array obtained with `VecGetArray()`.

2772:   This routine actually zeros out the `a` pointer.

2774: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
2775:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
2776:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2777: @*/
2778: PetscErrorCode VecRestoreArray2dWrite(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
2779: {
2780:   void *dummy;

2782:   PetscFunctionBegin;
2784:   PetscAssertPointer(a, 6);
2786:   dummy = (void *)(*a + mstart);
2787:   PetscCall(PetscFree(dummy));
2788:   PetscCall(VecRestoreArrayWrite(x, NULL));
2789:   PetscFunctionReturn(PETSC_SUCCESS);
2790: }

2792: /*@C
2793:   VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this
2794:   processor's portion of the vector data.  You MUST call `VecRestoreArray1d()`
2795:   when you no longer need access to the array.

2797:   Logically Collective

2799:   Input Parameters:
2800: + x      - the vector
2801: . m      - first dimension of two dimensional array
2802: - mstart - first index you will use in first coordinate direction (often 0)

2804:   Output Parameter:
2805: . a - location to put pointer to the array

2807:   Level: developer

2809:   Notes:
2810:   For a vector obtained from `DMCreateLocalVector()` `mstart` is likely
2811:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
2812:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`.

2814:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2816: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
2817:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
2818:           `VecGetArray2d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2819: @*/
2820: PetscErrorCode VecGetArray1d(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
2821: {
2822:   PetscInt N;

2824:   PetscFunctionBegin;
2826:   PetscAssertPointer(a, 4);
2828:   PetscCall(VecGetLocalSize(x, &N));
2829:   PetscCheck(m == N, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Local array size %" PetscInt_FMT " does not match 1d array dimensions %" PetscInt_FMT, N, m);
2830:   PetscCall(VecGetArray(x, a));
2831:   *a -= mstart;
2832:   PetscFunctionReturn(PETSC_SUCCESS);
2833: }

2835: /*@C
2836:   VecGetArray1dWrite - Returns a pointer to a 1d contiguous array that will contain this
2837:   processor's portion of the vector data.  You MUST call `VecRestoreArray1dWrite()`
2838:   when you no longer need access to the array.

2840:   Logically Collective

2842:   Input Parameters:
2843: + x      - the vector
2844: . m      - first dimension of two dimensional array
2845: - mstart - first index you will use in first coordinate direction (often 0)

2847:   Output Parameter:
2848: . a - location to put pointer to the array

2850:   Level: developer

2852:   Notes:
2853:   For a vector obtained from `DMCreateLocalVector()` `mstart` is likely
2854:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
2855:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`.

2857:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2859: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
2860:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
2861:           `VecGetArray2d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2862: @*/
2863: PetscErrorCode VecGetArray1dWrite(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
2864: {
2865:   PetscInt N;

2867:   PetscFunctionBegin;
2869:   PetscAssertPointer(a, 4);
2871:   PetscCall(VecGetLocalSize(x, &N));
2872:   PetscCheck(m == N, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Local array size %" PetscInt_FMT " does not match 1d array dimensions %" PetscInt_FMT, N, m);
2873:   PetscCall(VecGetArrayWrite(x, a));
2874:   *a -= mstart;
2875:   PetscFunctionReturn(PETSC_SUCCESS);
2876: }

2878: /*@C
2879:   VecRestoreArray1d - Restores a vector after `VecGetArray1d()` has been called.

2881:   Logically Collective

2883:   Input Parameters:
2884: + x      - the vector
2885: . m      - first dimension of two dimensional array
2886: . mstart - first index you will use in first coordinate direction (often 0)
2887: - a      - location of pointer to array obtained from `VecGetArray1d()`

2889:   Level: developer

2891:   Notes:
2892:   For regular PETSc vectors this routine does not involve any copies. For
2893:   any special vectors that do not store local vector data in a contiguous
2894:   array, this routine will copy the data back into the underlying
2895:   vector data structure from the array obtained with `VecGetArray1d()`.

2897:   This routine actually zeros out the `a` pointer.

2899: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
2900:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
2901:           `VecGetArray1d()`, `VecRestoreArray2d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2902: @*/
2903: PetscErrorCode VecRestoreArray1d(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
2904: {
2905:   PetscFunctionBegin;
2908:   PetscCall(VecRestoreArray(x, NULL));
2909:   *a = NULL;
2910:   PetscFunctionReturn(PETSC_SUCCESS);
2911: }

2913: /*@C
2914:   VecRestoreArray1dWrite - Restores a vector after `VecGetArray1dWrite()` has been called.

2916:   Logically Collective

2918:   Input Parameters:
2919: + x      - the vector
2920: . m      - first dimension of two dimensional array
2921: . mstart - first index you will use in first coordinate direction (often 0)
2922: - a      - location of pointer to array obtained from `VecGetArray1d()`

2924:   Level: developer

2926:   Notes:
2927:   For regular PETSc vectors this routine does not involve any copies. For
2928:   any special vectors that do not store local vector data in a contiguous
2929:   array, this routine will copy the data back into the underlying
2930:   vector data structure from the array obtained with `VecGetArray1d()`.

2932:   This routine actually zeros out the `a` pointer.

2934: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
2935:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
2936:           `VecGetArray1d()`, `VecRestoreArray2d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2937: @*/
2938: PetscErrorCode VecRestoreArray1dWrite(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
2939: {
2940:   PetscFunctionBegin;
2943:   PetscCall(VecRestoreArrayWrite(x, NULL));
2944:   *a = NULL;
2945:   PetscFunctionReturn(PETSC_SUCCESS);
2946: }

2948: /*@C
2949:   VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this
2950:   processor's portion of the vector data.  You MUST call `VecRestoreArray3d()`
2951:   when you no longer need access to the array.

2953:   Logically Collective

2955:   Input Parameters:
2956: + x      - the vector
2957: . m      - first dimension of three dimensional array
2958: . n      - second dimension of three dimensional array
2959: . p      - third dimension of three dimensional array
2960: . mstart - first index you will use in first coordinate direction (often 0)
2961: . nstart - first index in the second coordinate direction (often 0)
2962: - pstart - first index in the third coordinate direction (often 0)

2964:   Output Parameter:
2965: . a - location to put pointer to the array

2967:   Level: developer

2969:   Notes:
2970:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
2971:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
2972:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
2973:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3d()`.

2975:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2977: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
2978:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecRestoreArray3d()`,
2979:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
2980: @*/
2981: PetscErrorCode VecGetArray3d(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
2982: {
2983:   PetscInt     i, N, j;
2984:   PetscScalar *aa, **b;

2986:   PetscFunctionBegin;
2988:   PetscAssertPointer(a, 8);
2990:   PetscCall(VecGetLocalSize(x, &N));
2991:   PetscCheck(m * n * p == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 3d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p);
2992:   PetscCall(VecGetArray(x, &aa));

2994:   PetscCall(PetscMalloc(m * sizeof(PetscScalar **) + m * n * sizeof(PetscScalar *), a));
2995:   b = (PetscScalar **)((*a) + m);
2996:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
2997:   for (i = 0; i < m; i++)
2998:     for (j = 0; j < n; j++) b[i * n + j] = PetscSafePointerPlusOffset(aa, i * n * p + j * p - pstart);
2999:   *a -= mstart;
3000:   PetscFunctionReturn(PETSC_SUCCESS);
3001: }

3003: /*@C
3004:   VecGetArray3dWrite - Returns a pointer to a 3d contiguous array that will contain this
3005:   processor's portion of the vector data.  You MUST call `VecRestoreArray3dWrite()`
3006:   when you no longer need access to the array.

3008:   Logically Collective

3010:   Input Parameters:
3011: + x      - the vector
3012: . m      - first dimension of three dimensional array
3013: . n      - second dimension of three dimensional array
3014: . p      - third dimension of three dimensional array
3015: . mstart - first index you will use in first coordinate direction (often 0)
3016: . nstart - first index in the second coordinate direction (often 0)
3017: - pstart - first index in the third coordinate direction (often 0)

3019:   Output Parameter:
3020: . a - location to put pointer to the array

3022:   Level: developer

3024:   Notes:
3025:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
3026:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3027:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3028:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3d()`.

3030:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3032: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3033:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3034:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3035: @*/
3036: PetscErrorCode VecGetArray3dWrite(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
3037: {
3038:   PetscInt     i, N, j;
3039:   PetscScalar *aa, **b;

3041:   PetscFunctionBegin;
3043:   PetscAssertPointer(a, 8);
3045:   PetscCall(VecGetLocalSize(x, &N));
3046:   PetscCheck(m * n * p == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 3d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p);
3047:   PetscCall(VecGetArrayWrite(x, &aa));

3049:   PetscCall(PetscMalloc(m * sizeof(PetscScalar **) + m * n * sizeof(PetscScalar *), a));
3050:   b = (PetscScalar **)((*a) + m);
3051:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
3052:   for (i = 0; i < m; i++)
3053:     for (j = 0; j < n; j++) b[i * n + j] = aa + i * n * p + j * p - pstart;

3055:   *a -= mstart;
3056:   PetscFunctionReturn(PETSC_SUCCESS);
3057: }

3059: /*@C
3060:   VecRestoreArray3d - Restores a vector after `VecGetArray3d()` has been called.

3062:   Logically Collective

3064:   Input Parameters:
3065: + x      - the vector
3066: . m      - first dimension of three dimensional array
3067: . n      - second dimension of the three dimensional array
3068: . p      - third dimension of the three dimensional array
3069: . mstart - first index you will use in first coordinate direction (often 0)
3070: . nstart - first index in the second coordinate direction (often 0)
3071: . pstart - first index in the third coordinate direction (often 0)
3072: - a      - location of pointer to array obtained from VecGetArray3d()

3074:   Level: developer

3076:   Notes:
3077:   For regular PETSc vectors this routine does not involve any copies. For
3078:   any special vectors that do not store local vector data in a contiguous
3079:   array, this routine will copy the data back into the underlying
3080:   vector data structure from the array obtained with `VecGetArray()`.

3082:   This routine actually zeros out the `a` pointer.

3084: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3085:           `VecGetArray2d()`, `VecGetArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3086:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3087: @*/
3088: PetscErrorCode VecRestoreArray3d(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
3089: {
3090:   void *dummy;

3092:   PetscFunctionBegin;
3094:   PetscAssertPointer(a, 8);
3096:   dummy = (void *)(*a + mstart);
3097:   PetscCall(PetscFree(dummy));
3098:   PetscCall(VecRestoreArray(x, NULL));
3099:   *a = NULL;
3100:   PetscFunctionReturn(PETSC_SUCCESS);
3101: }

3103: /*@C
3104:   VecRestoreArray3dWrite - Restores a vector after `VecGetArray3dWrite()` has been called.

3106:   Logically Collective

3108:   Input Parameters:
3109: + x      - the vector
3110: . m      - first dimension of three dimensional array
3111: . n      - second dimension of the three dimensional array
3112: . p      - third dimension of the three dimensional array
3113: . mstart - first index you will use in first coordinate direction (often 0)
3114: . nstart - first index in the second coordinate direction (often 0)
3115: . pstart - first index in the third coordinate direction (often 0)
3116: - a      - location of pointer to array obtained from VecGetArray3d()

3118:   Level: developer

3120:   Notes:
3121:   For regular PETSc vectors this routine does not involve any copies. For
3122:   any special vectors that do not store local vector data in a contiguous
3123:   array, this routine will copy the data back into the underlying
3124:   vector data structure from the array obtained with `VecGetArray()`.

3126:   This routine actually zeros out the `a` pointer.

3128: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3129:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3130:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3131: @*/
3132: PetscErrorCode VecRestoreArray3dWrite(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
3133: {
3134:   void *dummy;

3136:   PetscFunctionBegin;
3138:   PetscAssertPointer(a, 8);
3140:   dummy = (void *)(*a + mstart);
3141:   PetscCall(PetscFree(dummy));
3142:   PetscCall(VecRestoreArrayWrite(x, NULL));
3143:   *a = NULL;
3144:   PetscFunctionReturn(PETSC_SUCCESS);
3145: }

3147: /*@C
3148:   VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this
3149:   processor's portion of the vector data.  You MUST call `VecRestoreArray4d()`
3150:   when you no longer need access to the array.

3152:   Logically Collective

3154:   Input Parameters:
3155: + x      - the vector
3156: . m      - first dimension of four dimensional array
3157: . n      - second dimension of four dimensional array
3158: . p      - third dimension of four dimensional array
3159: . q      - fourth dimension of four dimensional array
3160: . mstart - first index you will use in first coordinate direction (often 0)
3161: . nstart - first index in the second coordinate direction (often 0)
3162: . pstart - first index in the third coordinate direction (often 0)
3163: - qstart - first index in the fourth coordinate direction (often 0)

3165:   Output Parameter:
3166: . a - location to put pointer to the array

3168:   Level: developer

3170:   Notes:
3171:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
3172:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3173:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3174:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3d()`.

3176:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3178: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3179:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3180:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecRestoreArray4d()`
3181: @*/
3182: PetscErrorCode VecGetArray4d(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3183: {
3184:   PetscInt     i, N, j, k;
3185:   PetscScalar *aa, ***b, **c;

3187:   PetscFunctionBegin;
3189:   PetscAssertPointer(a, 10);
3191:   PetscCall(VecGetLocalSize(x, &N));
3192:   PetscCheck(m * n * p * q == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 4d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p, q);
3193:   PetscCall(VecGetArray(x, &aa));

3195:   PetscCall(PetscMalloc(m * sizeof(PetscScalar ***) + m * n * sizeof(PetscScalar **) + m * n * p * sizeof(PetscScalar *), a));
3196:   b = (PetscScalar ***)((*a) + m);
3197:   c = (PetscScalar **)(b + m * n);
3198:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
3199:   for (i = 0; i < m; i++)
3200:     for (j = 0; j < n; j++) b[i * n + j] = c + i * n * p + j * p - pstart;
3201:   for (i = 0; i < m; i++)
3202:     for (j = 0; j < n; j++)
3203:       for (k = 0; k < p; k++) c[i * n * p + j * p + k] = aa + i * n * p * q + j * p * q + k * q - qstart;
3204:   *a -= mstart;
3205:   PetscFunctionReturn(PETSC_SUCCESS);
3206: }

3208: /*@C
3209:   VecGetArray4dWrite - Returns a pointer to a 4d contiguous array that will contain this
3210:   processor's portion of the vector data.  You MUST call `VecRestoreArray4dWrite()`
3211:   when you no longer need access to the array.

3213:   Logically Collective

3215:   Input Parameters:
3216: + x      - the vector
3217: . m      - first dimension of four dimensional array
3218: . n      - second dimension of four dimensional array
3219: . p      - third dimension of four dimensional array
3220: . q      - fourth dimension of four dimensional array
3221: . mstart - first index you will use in first coordinate direction (often 0)
3222: . nstart - first index in the second coordinate direction (often 0)
3223: . pstart - first index in the third coordinate direction (often 0)
3224: - qstart - first index in the fourth coordinate direction (often 0)

3226:   Output Parameter:
3227: . a - location to put pointer to the array

3229:   Level: developer

3231:   Notes:
3232:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
3233:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3234:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3235:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3d()`.

3237:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3239: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3240:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3241:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3242: @*/
3243: PetscErrorCode VecGetArray4dWrite(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3244: {
3245:   PetscInt     i, N, j, k;
3246:   PetscScalar *aa, ***b, **c;

3248:   PetscFunctionBegin;
3250:   PetscAssertPointer(a, 10);
3252:   PetscCall(VecGetLocalSize(x, &N));
3253:   PetscCheck(m * n * p * q == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 4d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p, q);
3254:   PetscCall(VecGetArrayWrite(x, &aa));

3256:   PetscCall(PetscMalloc(m * sizeof(PetscScalar ***) + m * n * sizeof(PetscScalar **) + m * n * p * sizeof(PetscScalar *), a));
3257:   b = (PetscScalar ***)((*a) + m);
3258:   c = (PetscScalar **)(b + m * n);
3259:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
3260:   for (i = 0; i < m; i++)
3261:     for (j = 0; j < n; j++) b[i * n + j] = c + i * n * p + j * p - pstart;
3262:   for (i = 0; i < m; i++)
3263:     for (j = 0; j < n; j++)
3264:       for (k = 0; k < p; k++) c[i * n * p + j * p + k] = aa + i * n * p * q + j * p * q + k * q - qstart;
3265:   *a -= mstart;
3266:   PetscFunctionReturn(PETSC_SUCCESS);
3267: }

3269: /*@C
3270:   VecRestoreArray4d - Restores a vector after `VecGetArray4d()` has been called.

3272:   Logically Collective

3274:   Input Parameters:
3275: + x      - the vector
3276: . m      - first dimension of four dimensional array
3277: . n      - second dimension of the four dimensional array
3278: . p      - third dimension of the four dimensional array
3279: . q      - fourth dimension of the four dimensional array
3280: . mstart - first index you will use in first coordinate direction (often 0)
3281: . nstart - first index in the second coordinate direction (often 0)
3282: . pstart - first index in the third coordinate direction (often 0)
3283: . qstart - first index in the fourth coordinate direction (often 0)
3284: - a      - location of pointer to array obtained from VecGetArray4d()

3286:   Level: developer

3288:   Notes:
3289:   For regular PETSc vectors this routine does not involve any copies. For
3290:   any special vectors that do not store local vector data in a contiguous
3291:   array, this routine will copy the data back into the underlying
3292:   vector data structure from the array obtained with `VecGetArray()`.

3294:   This routine actually zeros out the `a` pointer.

3296: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3297:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3298:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`
3299: @*/
3300: PetscErrorCode VecRestoreArray4d(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3301: {
3302:   void *dummy;

3304:   PetscFunctionBegin;
3306:   PetscAssertPointer(a, 10);
3308:   dummy = (void *)(*a + mstart);
3309:   PetscCall(PetscFree(dummy));
3310:   PetscCall(VecRestoreArray(x, NULL));
3311:   *a = NULL;
3312:   PetscFunctionReturn(PETSC_SUCCESS);
3313: }

3315: /*@C
3316:   VecRestoreArray4dWrite - Restores a vector after `VecGetArray4dWrite()` has been called.

3318:   Logically Collective

3320:   Input Parameters:
3321: + x      - the vector
3322: . m      - first dimension of four dimensional array
3323: . n      - second dimension of the four dimensional array
3324: . p      - third dimension of the four dimensional array
3325: . q      - fourth dimension of the four dimensional array
3326: . mstart - first index you will use in first coordinate direction (often 0)
3327: . nstart - first index in the second coordinate direction (often 0)
3328: . pstart - first index in the third coordinate direction (often 0)
3329: . qstart - first index in the fourth coordinate direction (often 0)
3330: - a      - location of pointer to array obtained from `VecGetArray4d()`

3332:   Level: developer

3334:   Notes:
3335:   For regular PETSc vectors this routine does not involve any copies. For
3336:   any special vectors that do not store local vector data in a contiguous
3337:   array, this routine will copy the data back into the underlying
3338:   vector data structure from the array obtained with `VecGetArray()`.

3340:   This routine actually zeros out the `a` pointer.

3342: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3343:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3344:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3345: @*/
3346: PetscErrorCode VecRestoreArray4dWrite(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3347: {
3348:   void *dummy;

3350:   PetscFunctionBegin;
3352:   PetscAssertPointer(a, 10);
3354:   dummy = (void *)(*a + mstart);
3355:   PetscCall(PetscFree(dummy));
3356:   PetscCall(VecRestoreArrayWrite(x, NULL));
3357:   *a = NULL;
3358:   PetscFunctionReturn(PETSC_SUCCESS);
3359: }

3361: /*@C
3362:   VecGetArray2dRead - Returns a pointer to a 2d contiguous array that contains this
3363:   processor's portion of the vector data.  You MUST call `VecRestoreArray2dRead()`
3364:   when you no longer need access to the array.

3366:   Logically Collective

3368:   Input Parameters:
3369: + x      - the vector
3370: . m      - first dimension of two dimensional array
3371: . n      - second dimension of two dimensional array
3372: . mstart - first index you will use in first coordinate direction (often 0)
3373: - nstart - first index in the second coordinate direction (often 0)

3375:   Output Parameter:
3376: . a - location to put pointer to the array

3378:   Level: developer

3380:   Notes:
3381:   For a vector obtained from `DMCreateLocalVector()` `mstart` and `nstart` are likely
3382:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3383:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3384:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray2d()`.

3386:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3388: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3389:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3390:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3391: @*/
3392: PetscErrorCode VecGetArray2dRead(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
3393: {
3394:   PetscInt           i, N;
3395:   const PetscScalar *aa;

3397:   PetscFunctionBegin;
3399:   PetscAssertPointer(a, 6);
3401:   PetscCall(VecGetLocalSize(x, &N));
3402:   PetscCheck(m * n == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 2d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n);
3403:   PetscCall(VecGetArrayRead(x, &aa));

3405:   PetscCall(PetscMalloc1(m, a));
3406:   for (i = 0; i < m; i++) (*a)[i] = (PetscScalar *)aa + i * n - nstart;
3407:   *a -= mstart;
3408:   PetscFunctionReturn(PETSC_SUCCESS);
3409: }

3411: /*@C
3412:   VecRestoreArray2dRead - Restores a vector after `VecGetArray2dRead()` has been called.

3414:   Logically Collective

3416:   Input Parameters:
3417: + x      - the vector
3418: . m      - first dimension of two dimensional array
3419: . n      - second dimension of the two dimensional array
3420: . mstart - first index you will use in first coordinate direction (often 0)
3421: . nstart - first index in the second coordinate direction (often 0)
3422: - a      - location of pointer to array obtained from VecGetArray2d()

3424:   Level: developer

3426:   Notes:
3427:   For regular PETSc vectors this routine does not involve any copies. For
3428:   any special vectors that do not store local vector data in a contiguous
3429:   array, this routine will copy the data back into the underlying
3430:   vector data structure from the array obtained with `VecGetArray()`.

3432:   This routine actually zeros out the `a` pointer.

3434: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3435:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3436:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3437: @*/
3438: PetscErrorCode VecRestoreArray2dRead(Vec x, PetscInt m, PetscInt n, PetscInt mstart, PetscInt nstart, PetscScalar **a[])
3439: {
3440:   void *dummy;

3442:   PetscFunctionBegin;
3444:   PetscAssertPointer(a, 6);
3446:   dummy = (void *)(*a + mstart);
3447:   PetscCall(PetscFree(dummy));
3448:   PetscCall(VecRestoreArrayRead(x, NULL));
3449:   *a = NULL;
3450:   PetscFunctionReturn(PETSC_SUCCESS);
3451: }

3453: /*@C
3454:   VecGetArray1dRead - Returns a pointer to a 1d contiguous array that contains this
3455:   processor's portion of the vector data.  You MUST call `VecRestoreArray1dRead()`
3456:   when you no longer need access to the array.

3458:   Logically Collective

3460:   Input Parameters:
3461: + x      - the vector
3462: . m      - first dimension of two dimensional array
3463: - mstart - first index you will use in first coordinate direction (often 0)

3465:   Output Parameter:
3466: . a - location to put pointer to the array

3468:   Level: developer

3470:   Notes:
3471:   For a vector obtained from `DMCreateLocalVector()` `mstart` is likely
3472:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3473:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`.

3475:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3477: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3478:           `VecRestoreArray2d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3479:           `VecGetArray2d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3480: @*/
3481: PetscErrorCode VecGetArray1dRead(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
3482: {
3483:   PetscInt N;

3485:   PetscFunctionBegin;
3487:   PetscAssertPointer(a, 4);
3489:   PetscCall(VecGetLocalSize(x, &N));
3490:   PetscCheck(m == N, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Local array size %" PetscInt_FMT " does not match 1d array dimensions %" PetscInt_FMT, N, m);
3491:   PetscCall(VecGetArrayRead(x, (const PetscScalar **)a));
3492:   *a -= mstart;
3493:   PetscFunctionReturn(PETSC_SUCCESS);
3494: }

3496: /*@C
3497:   VecRestoreArray1dRead - Restores a vector after `VecGetArray1dRead()` has been called.

3499:   Logically Collective

3501:   Input Parameters:
3502: + x      - the vector
3503: . m      - first dimension of two dimensional array
3504: . mstart - first index you will use in first coordinate direction (often 0)
3505: - a      - location of pointer to array obtained from `VecGetArray1dRead()`

3507:   Level: developer

3509:   Notes:
3510:   For regular PETSc vectors this routine does not involve any copies. For
3511:   any special vectors that do not store local vector data in a contiguous
3512:   array, this routine will copy the data back into the underlying
3513:   vector data structure from the array obtained with `VecGetArray1dRead()`.

3515:   This routine actually zeros out the `a` pointer.

3517: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3518:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3519:           `VecGetArray1d()`, `VecRestoreArray2d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3520: @*/
3521: PetscErrorCode VecRestoreArray1dRead(Vec x, PetscInt m, PetscInt mstart, PetscScalar *a[])
3522: {
3523:   PetscFunctionBegin;
3526:   PetscCall(VecRestoreArrayRead(x, NULL));
3527:   *a = NULL;
3528:   PetscFunctionReturn(PETSC_SUCCESS);
3529: }

3531: /*@C
3532:   VecGetArray3dRead - Returns a pointer to a 3d contiguous array that contains this
3533:   processor's portion of the vector data.  You MUST call `VecRestoreArray3dRead()`
3534:   when you no longer need access to the array.

3536:   Logically Collective

3538:   Input Parameters:
3539: + x      - the vector
3540: . m      - first dimension of three dimensional array
3541: . n      - second dimension of three dimensional array
3542: . p      - third dimension of three dimensional array
3543: . mstart - first index you will use in first coordinate direction (often 0)
3544: . nstart - first index in the second coordinate direction (often 0)
3545: - pstart - first index in the third coordinate direction (often 0)

3547:   Output Parameter:
3548: . a - location to put pointer to the array

3550:   Level: developer

3552:   Notes:
3553:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
3554:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3555:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3556:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3dRead()`.

3558:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3560: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3561:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3562:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3563: @*/
3564: PetscErrorCode VecGetArray3dRead(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
3565: {
3566:   PetscInt           i, N, j;
3567:   const PetscScalar *aa;
3568:   PetscScalar      **b;

3570:   PetscFunctionBegin;
3572:   PetscAssertPointer(a, 8);
3574:   PetscCall(VecGetLocalSize(x, &N));
3575:   PetscCheck(m * n * p == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 3d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p);
3576:   PetscCall(VecGetArrayRead(x, &aa));

3578:   PetscCall(PetscMalloc(m * sizeof(PetscScalar **) + m * n * sizeof(PetscScalar *), a));
3579:   b = (PetscScalar **)((*a) + m);
3580:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
3581:   for (i = 0; i < m; i++)
3582:     for (j = 0; j < n; j++) b[i * n + j] = PetscSafePointerPlusOffset((PetscScalar *)aa, i * n * p + j * p - pstart);
3583:   *a -= mstart;
3584:   PetscFunctionReturn(PETSC_SUCCESS);
3585: }

3587: /*@C
3588:   VecRestoreArray3dRead - Restores a vector after `VecGetArray3dRead()` has been called.

3590:   Logically Collective

3592:   Input Parameters:
3593: + x      - the vector
3594: . m      - first dimension of three dimensional array
3595: . n      - second dimension of the three dimensional array
3596: . p      - third dimension of the three dimensional array
3597: . mstart - first index you will use in first coordinate direction (often 0)
3598: . nstart - first index in the second coordinate direction (often 0)
3599: . pstart - first index in the third coordinate direction (often 0)
3600: - a      - location of pointer to array obtained from `VecGetArray3dRead()`

3602:   Level: developer

3604:   Notes:
3605:   For regular PETSc vectors this routine does not involve any copies. For
3606:   any special vectors that do not store local vector data in a contiguous
3607:   array, this routine will copy the data back into the underlying
3608:   vector data structure from the array obtained with `VecGetArray()`.

3610:   This routine actually zeros out the `a` pointer.

3612: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3613:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3614:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3615: @*/
3616: PetscErrorCode VecRestoreArray3dRead(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscScalar ***a[])
3617: {
3618:   void *dummy;

3620:   PetscFunctionBegin;
3622:   PetscAssertPointer(a, 8);
3624:   dummy = (void *)(*a + mstart);
3625:   PetscCall(PetscFree(dummy));
3626:   PetscCall(VecRestoreArrayRead(x, NULL));
3627:   *a = NULL;
3628:   PetscFunctionReturn(PETSC_SUCCESS);
3629: }

3631: /*@C
3632:   VecGetArray4dRead - Returns a pointer to a 4d contiguous array that contains this
3633:   processor's portion of the vector data.  You MUST call `VecRestoreArray4dRead()`
3634:   when you no longer need access to the array.

3636:   Logically Collective

3638:   Input Parameters:
3639: + x      - the vector
3640: . m      - first dimension of four dimensional array
3641: . n      - second dimension of four dimensional array
3642: . p      - third dimension of four dimensional array
3643: . q      - fourth dimension of four dimensional array
3644: . mstart - first index you will use in first coordinate direction (often 0)
3645: . nstart - first index in the second coordinate direction (often 0)
3646: . pstart - first index in the third coordinate direction (often 0)
3647: - qstart - first index in the fourth coordinate direction (often 0)

3649:   Output Parameter:
3650: . a - location to put pointer to the array

3652:   Level: beginner

3654:   Notes:
3655:   For a vector obtained from `DMCreateLocalVector()` `mstart`, `nstart`, and `pstart` are likely
3656:   obtained from the corner indices obtained from `DMDAGetGhostCorners()` while for
3657:   `DMCreateGlobalVector()` they are the corner indices from `DMDAGetCorners()`. In both cases
3658:   the arguments from `DMDAGet[Ghost]Corners()` are reversed in the call to `VecGetArray3d()`.

3660:   For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3662: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecGetArrays()`, `VecPlaceArray()`,
3663:           `VecRestoreArray2d()`, `DMDAVecGetarray()`, `DMDAVecRestoreArray()`, `VecGetArray3d()`, `VecRestoreArray3d()`,
3664:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3665: @*/
3666: PetscErrorCode VecGetArray4dRead(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3667: {
3668:   PetscInt           i, N, j, k;
3669:   const PetscScalar *aa;
3670:   PetscScalar     ***b, **c;

3672:   PetscFunctionBegin;
3674:   PetscAssertPointer(a, 10);
3676:   PetscCall(VecGetLocalSize(x, &N));
3677:   PetscCheck(m * n * p * q == N, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local array size %" PetscInt_FMT " does not match 4d array dimensions %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT " by %" PetscInt_FMT, N, m, n, p, q);
3678:   PetscCall(VecGetArrayRead(x, &aa));

3680:   PetscCall(PetscMalloc(m * sizeof(PetscScalar ***) + m * n * sizeof(PetscScalar **) + m * n * p * sizeof(PetscScalar *), a));
3681:   b = (PetscScalar ***)((*a) + m);
3682:   c = (PetscScalar **)(b + m * n);
3683:   for (i = 0; i < m; i++) (*a)[i] = b + i * n - nstart;
3684:   for (i = 0; i < m; i++)
3685:     for (j = 0; j < n; j++) b[i * n + j] = c + i * n * p + j * p - pstart;
3686:   for (i = 0; i < m; i++)
3687:     for (j = 0; j < n; j++)
3688:       for (k = 0; k < p; k++) c[i * n * p + j * p + k] = (PetscScalar *)aa + i * n * p * q + j * p * q + k * q - qstart;
3689:   *a -= mstart;
3690:   PetscFunctionReturn(PETSC_SUCCESS);
3691: }

3693: /*@C
3694:   VecRestoreArray4dRead - Restores a vector after `VecGetArray4d()` has been called.

3696:   Logically Collective

3698:   Input Parameters:
3699: + x      - the vector
3700: . m      - first dimension of four dimensional array
3701: . n      - second dimension of the four dimensional array
3702: . p      - third dimension of the four dimensional array
3703: . q      - fourth dimension of the four dimensional array
3704: . mstart - first index you will use in first coordinate direction (often 0)
3705: . nstart - first index in the second coordinate direction (often 0)
3706: . pstart - first index in the third coordinate direction (often 0)
3707: . qstart - first index in the fourth coordinate direction (often 0)
3708: - a      - location of pointer to array obtained from `VecGetArray4dRead()`

3710:   Level: beginner

3712:   Notes:
3713:   For regular PETSc vectors this routine does not involve any copies. For
3714:   any special vectors that do not store local vector data in a contiguous
3715:   array, this routine will copy the data back into the underlying
3716:   vector data structure from the array obtained with `VecGetArray()`.

3718:   This routine actually zeros out the `a` pointer.

3720: .seealso: [](ch_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecRestoreArrays()`, `VecPlaceArray()`,
3721:           `VecGetArray2d()`, `VecGetArray3d()`, `VecRestoreArray3d()`, `DMDAVecGetArray()`, `DMDAVecRestoreArray()`
3722:           `VecGetArray1d()`, `VecRestoreArray1d()`, `VecGetArray4d()`, `VecRestoreArray4d()`
3723: @*/
3724: PetscErrorCode VecRestoreArray4dRead(Vec x, PetscInt m, PetscInt n, PetscInt p, PetscInt q, PetscInt mstart, PetscInt nstart, PetscInt pstart, PetscInt qstart, PetscScalar ****a[])
3725: {
3726:   void *dummy;

3728:   PetscFunctionBegin;
3730:   PetscAssertPointer(a, 10);
3732:   dummy = (void *)(*a + mstart);
3733:   PetscCall(PetscFree(dummy));
3734:   PetscCall(VecRestoreArrayRead(x, NULL));
3735:   *a = NULL;
3736:   PetscFunctionReturn(PETSC_SUCCESS);
3737: }

3739: /*@
3740:   VecLockGet - Get the current lock status of a vector

3742:   Logically Collective

3744:   Input Parameter:
3745: . x - the vector

3747:   Output Parameter:
3748: . state - greater than zero indicates the vector is locked for read; less than zero indicates the vector is
3749:            locked for write; equal to zero means the vector is unlocked, that is, it is free to read or write.

3751:   Level: advanced

3753: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecLockReadPush()`, `VecLockReadPop()`
3754: @*/
3755: PetscErrorCode VecLockGet(Vec x, PetscInt *state)
3756: {
3757:   PetscFunctionBegin;
3759:   PetscAssertPointer(state, 2);
3760:   *state = x->lock;
3761:   PetscFunctionReturn(PETSC_SUCCESS);
3762: }

3764: PetscErrorCode VecLockGetLocation(Vec x, const char *file[], const char *func[], int *line)
3765: {
3766:   PetscFunctionBegin;
3768:   PetscAssertPointer(file, 2);
3769:   PetscAssertPointer(func, 3);
3770:   PetscAssertPointer(line, 4);
3771: #if PetscDefined(USE_DEBUG) && !PetscDefined(HAVE_THREADSAFETY)
3772:   {
3773:     const int index = x->lockstack.currentsize - 1;

3775:     *file = index < 0 ? NULL : x->lockstack.file[index];
3776:     *func = index < 0 ? NULL : x->lockstack.function[index];
3777:     *line = index < 0 ? 0 : x->lockstack.line[index];
3778:   }
3779: #else
3780:   *file = NULL;
3781:   *func = NULL;
3782:   *line = 0;
3783: #endif
3784:   PetscFunctionReturn(PETSC_SUCCESS);
3785: }

3787: /*@
3788:   VecLockReadPush - Push a read-only lock on a vector to prevent it from being written to

3790:   Logically Collective

3792:   Input Parameter:
3793: . x - the vector

3795:   Level: intermediate

3797:   Notes:
3798:   If this is set then calls to `VecGetArray()` or `VecSetValues()` or any other routines that change the vectors values will generate an error.

3800:   The call can be nested, i.e., called multiple times on the same vector, but each `VecLockReadPush()` has to have one matching
3801:   `VecLockReadPop()`, which removes the latest read-only lock.

3803: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecLockReadPop()`, `VecLockGet()`
3804: @*/
3805: PetscErrorCode VecLockReadPush(Vec x)
3806: {
3807:   PetscFunctionBegin;
3809:   PetscCheck(x->lock++ >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vector is already locked for exclusive write access but you want to read it");
3810: #if PetscDefined(USE_DEBUG) && !PetscDefined(HAVE_THREADSAFETY)
3811:   {
3812:     const char *file, *func;
3813:     int         index, line;

3815:     if ((index = petscstack.currentsize - 2) < 0) {
3816:       // vec was locked "outside" of petsc, either in user-land or main. the error message will
3817:       // now show this function as the culprit, but it will include the stacktrace
3818:       file = "unknown user-file";
3819:       func = "unknown_user_function";
3820:       line = 0;
3821:     } else {
3822:       file = petscstack.file[index];
3823:       func = petscstack.function[index];
3824:       line = petscstack.line[index];
3825:     }
3826:     PetscStackPush_Private(x->lockstack, file, func, line, petscstack.petscroutine[index], PETSC_FALSE);
3827:   }
3828: #endif
3829:   PetscFunctionReturn(PETSC_SUCCESS);
3830: }

3832: /*@
3833:   VecLockReadPop - Pop a read-only lock from a vector

3835:   Logically Collective

3837:   Input Parameter:
3838: . x - the vector

3840:   Level: intermediate

3842: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecLockReadPush()`, `VecLockGet()`
3843: @*/
3844: PetscErrorCode VecLockReadPop(Vec x)
3845: {
3846:   PetscFunctionBegin;
3848:   PetscCheck(--x->lock >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vector has been unlocked from read-only access too many times");
3849: #if PetscDefined(USE_DEBUG) && !PetscDefined(HAVE_THREADSAFETY)
3850:   {
3851:     const char *previous = x->lockstack.function[x->lockstack.currentsize - 1];

3853:     PetscStackPop_Private(x->lockstack, previous);
3854:   }
3855: #endif
3856:   PetscFunctionReturn(PETSC_SUCCESS);
3857: }

3859: /*@
3860:   VecLockWriteSet - Lock or unlock a vector for exclusive read/write access

3862:   Logically Collective

3864:   Input Parameters:
3865: + x   - the vector
3866: - flg - `PETSC_TRUE` to lock the vector for exclusive read/write access; `PETSC_FALSE` to unlock it.

3868:   Level: intermediate

3870:   Notes:
3871:   The function is useful in split-phase computations, which usually have a begin phase and an end phase.
3872:   One can call `VecLockWriteSet`(x,`PETSC_TRUE`) in the begin phase to lock a vector for exclusive
3873:   access, and call `VecLockWriteSet`(x,`PETSC_FALSE`) in the end phase to unlock the vector from exclusive
3874:   access. In this way, one is ensured no other operations can access the vector in between. The code may like

3876: .vb
3877:        VecGetArray(x,&xdata); // begin phase
3878:        VecLockWriteSet(v,PETSC_TRUE);

3880:        Other operations, which can not access x anymore (they can access xdata, of course)

3882:        VecRestoreArray(x,&vdata); // end phase
3883:        VecLockWriteSet(v,PETSC_FALSE);
3884: .ve

3886:   The call can not be nested on the same vector, in other words, one can not call `VecLockWriteSet`(x,`PETSC_TRUE`)
3887:   again before calling `VecLockWriteSet`(v,`PETSC_FALSE`).

3889: .seealso: [](ch_vectors), `Vec`, `VecRestoreArray()`, `VecGetArrayRead()`, `VecLockReadPush()`, `VecLockReadPop()`, `VecLockGet()`
3890: @*/
3891: PetscErrorCode VecLockWriteSet(Vec x, PetscBool flg)
3892: {
3893:   PetscFunctionBegin;
3895:   if (flg) {
3896:     PetscCheck(x->lock <= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vector is already locked for read-only access but you want to write it");
3897:     PetscCheck(x->lock >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vector is already locked for exclusive write access but you want to write it");
3898:     x->lock = -1;
3899:   } else {
3900:     PetscCheck(x->lock == -1, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "Vector is not locked for exclusive write access but you want to unlock it from that");
3901:     x->lock = 0;
3902:   }
3903:   PetscFunctionReturn(PETSC_SUCCESS);
3904: }