Actual source code: vector.c

  1: /*
  2:      Provides the interface functions for vector operations that do NOT have PetscScalar/PetscReal in the signature
  3:    These are the vector functions the user calls.
  4: */
  5: #include <petsc/private/vecimpl.h>
  6: #include <petsc/private/deviceimpl.h>

  8: /* Logging support */
  9: PetscClassId  VEC_CLASSID;
 10: PetscLogEvent VEC_View, VEC_Max, VEC_Min, VEC_Dot, VEC_MDot, VEC_TDot;
 11: PetscLogEvent VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY;
 12: PetscLogEvent VEC_MTDot, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin, VEC_ScatterBegin, VEC_ScatterEnd;
 13: PetscLogEvent VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_SetPreallocateCOO, VEC_SetValuesCOO;
 14: PetscLogEvent VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceCommunication, VEC_ReduceBegin, VEC_ReduceEnd, VEC_Ops;
 15: PetscLogEvent VEC_DotNorm2, VEC_AXPBYPCZ;
 16: PetscLogEvent VEC_ViennaCLCopyFromGPU, VEC_ViennaCLCopyToGPU;
 17: PetscLogEvent VEC_CUDACopyFromGPU, VEC_CUDACopyToGPU;
 18: PetscLogEvent VEC_CUDACopyFromGPUSome, VEC_CUDACopyToGPUSome;
 19: PetscLogEvent VEC_HIPCopyFromGPU, VEC_HIPCopyToGPU;
 20: PetscLogEvent VEC_HIPCopyFromGPUSome, VEC_HIPCopyToGPUSome;

 22: /*@
 23:    VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
 24:        to be communicated to other processors during the VecAssemblyBegin/End() process

 26:     Not collective

 28:    Input Parameter:
 29: .   vec - the vector

 31:    Output Parameters:
 32: +   nstash   - the size of the stash
 33: .   reallocs - the number of additional mallocs incurred.
 34: .   bnstash   - the size of the block stash
 35: -   breallocs - the number of additional mallocs incurred.in the block stash

 37:    Level: advanced

 39: .seealso: [](chapter_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `Vec`, `VecStashSetInitialSize()`, `VecStashView()`
 40: @*/
 41: PetscErrorCode VecStashGetInfo(Vec vec, PetscInt *nstash, PetscInt *reallocs, PetscInt *bnstash, PetscInt *breallocs)
 42: {
 43:   VecStashGetInfo_Private(&vec->stash, nstash, reallocs);
 44:   VecStashGetInfo_Private(&vec->bstash, bnstash, breallocs);
 45:   return 0;
 46: }

 48: /*@
 49:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
 50:    by the routine `VecSetValuesLocal()` to allow users to insert vector entries
 51:    using a local (per-processor) numbering.

 53:    Logically Collective

 55:    Input Parameters:
 56: +  x - vector
 57: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

 59:    Level: intermediate

 61:  Note:
 62:    All vectors obtained with `VecDuplicate()` from this vector inherit the same mapping.

 64: seealso: [](chapter_vectors), `Vec`, `VecAssemblyBegin()`, `VecAssemblyEnd()`, `VecSetValues()`, `VecSetValuesLocal()`,
 65:            `VecSetLocalToGlobalMapping()`, `VecSetValuesBlockedLocal()`
 66: @*/
 67: PetscErrorCode VecSetLocalToGlobalMapping(Vec x, ISLocalToGlobalMapping mapping)
 68: {
 71:   if (x->ops->setlocaltoglobalmapping) PetscUseTypeMethod(x, setlocaltoglobalmapping, mapping);
 72:   else PetscLayoutSetISLocalToGlobalMapping(x->map, mapping);
 73:   return 0;
 74: }

 76: /*@
 77:    VecGetLocalToGlobalMapping - Gets the local-to-global numbering set by `VecSetLocalToGlobalMapping()`

 79:    Not Collective

 81:    Input Parameter:
 82: .  X - the vector

 84:    Output Parameter:
 85: .  mapping - the mapping

 87:    Level: advanced

 89: .seealso: [](chapter_vectors), `Vec`, `VecSetValuesLocal()`
 90: @*/
 91: PetscErrorCode VecGetLocalToGlobalMapping(Vec X, ISLocalToGlobalMapping *mapping)
 92: {
 96:   *mapping = X->map->mapping;
 97:   return 0;
 98: }

100: /*@
101:    VecAssemblyBegin - Begins assembling the vector.  This routine should
102:    be called after completing all calls to `VecSetValues()`.

104:    Collective

106:    Input Parameter:
107: .  vec - the vector

109:    Level: beginner

111: .seealso: [](chapter_vectors), `Vec`, `VecAssemblyEnd()`, `VecSetValues()`
112: @*/
113: PetscErrorCode VecAssemblyBegin(Vec vec)
114: {
117:   VecStashViewFromOptions(vec, NULL, "-vec_view_stash");
118:   PetscLogEventBegin(VEC_AssemblyBegin, vec, 0, 0, 0);
119:   PetscTryTypeMethod(vec, assemblybegin);
120:   PetscLogEventEnd(VEC_AssemblyBegin, vec, 0, 0, 0);
121:   PetscObjectStateIncrease((PetscObject)vec);
122:   return 0;
123: }

125: /*@
126:    VecAssemblyEnd - Completes assembling the vector.  This routine should
127:    be called after `VecAssemblyBegin()`.

129:    Collective

131:    Input Parameter:
132: .  vec - the vector

134:    Options Database Keys:
135: +  -vec_view - Prints vector in `PETSC_VIEWER_DEFAULT` format
136: .  -vec_view ::ascii_matlab - Prints vector in `PETSC_VIEWER_ASCII_MATLAB` format to stdout
137: .  -vec_view matlab:filename - Prints vector in MATLAB .mat file to filename (requires PETSc configured with --with-matlab)
138: .  -vec_view draw - Activates vector viewing using drawing tools
139: .  -display <name> - Sets display name (default is host)
140: .  -draw_pause <sec> - Sets number of seconds to pause after display
141: -  -vec_view socket - Activates vector viewing using a socket

143:    Level: beginner

145: .seealso: [](chapter_vectors), `Vec`, `VecAssemblyBegin()`, `VecSetValues()`
146: @*/
147: PetscErrorCode VecAssemblyEnd(Vec vec)
148: {
150:   PetscLogEventBegin(VEC_AssemblyEnd, vec, 0, 0, 0);
152:   PetscTryTypeMethod(vec, assemblyend);
153:   PetscLogEventEnd(VEC_AssemblyEnd, vec, 0, 0, 0);
154:   VecViewFromOptions(vec, NULL, "-vec_view");
155:   return 0;
156: }

158: /*@
159:    VecSetPreallocationCOO - set preallocation for a vector using a coordinate format of the entries with global indices

161:    Collective

163:    Input Parameters:
164: +  x - vector being preallocated
165: .  ncoo - number of entries
166: -  coo_i - entry indices

168:    Level: beginner

170:    Notes:
171:    Entries can be repeated, see `VecSetValuesCOO()`. Negative indices are not allowed unless vector option `VEC_IGNORE_NEGATIVE_INDICES` is set,
172:    in which case they, along with the corresponding entries in `VecSetValuesCOO()`, are ignored. If vector option `VEC_NO_OFF_PROC_ENTRIES` is set,
173:    remote entries are ignored, otherwise, they will be properly added or inserted to the vector.

175:    The array coo_i[] may be freed immediately after calling this function.

177: .seealso: [](chapter_vectors), `Vec`, VecSetValuesCOO(), VecSetPreallocationCOOLocal()
178: @*/
179: PetscErrorCode VecSetPreallocationCOO(Vec x, PetscCount ncoo, const PetscInt coo_i[])
180: {
184:   PetscLogEventBegin(VEC_SetPreallocateCOO, x, 0, 0, 0);
185:   PetscLayoutSetUp(x->map);
186:   if (x->ops->setpreallocationcoo) {
187:     PetscUseTypeMethod(x, setpreallocationcoo, ncoo, coo_i);
188:   } else {
189:     IS is_coo_i;
190:     /* The default implementation only supports ncoo within limit of PetscInt */
192:     ISCreateGeneral(PETSC_COMM_SELF, ncoo, coo_i, PETSC_COPY_VALUES, &is_coo_i);
193:     PetscObjectCompose((PetscObject)x, "__PETSc_coo_i", (PetscObject)is_coo_i);
194:     ISDestroy(&is_coo_i);
195:   }
196:   PetscLogEventEnd(VEC_SetPreallocateCOO, x, 0, 0, 0);
197:   return 0;
198: }

200: /*@
201:    VecSetPreallocationCOOLocal - set preallocation for vectors using a coordinate format of the entries with local indices

203:    Collective

205:    Input Parameters:
206: +  x - vector being preallocated
207: .  ncoo - number of entries
208: -  coo_i - row indices (local numbering; may be modified)

210:    Level: beginner

212:    Notes:
213:    The local indices are translated using the local to global mapping, thus `VecSetLocalToGlobalMapping()` must have been
214:    called prior to this function.

216:    The indices coo_i may be modified within this function. They might be translated to corresponding global
217:    indices, but the caller should not rely on them having any specific value after this function returns. The arrays
218:    can be freed or reused immediately after this function returns.

220:    Entries can be repeated. Negative indices and remote indices might be allowed. see `VecSetPreallocationCOO()`.

222: .seealso: [](chapter_vectors), `Vec`, VecSetPreallocationCOO(), VecSetValuesCOO()
223: @*/
224: PetscErrorCode VecSetPreallocationCOOLocal(Vec x, PetscCount ncoo, PetscInt coo_i[])
225: {
226:   ISLocalToGlobalMapping ltog;

232:   PetscLayoutSetUp(x->map);
233:   VecGetLocalToGlobalMapping(x, &ltog);
234:   if (ltog) ISLocalToGlobalMappingApply(ltog, ncoo, coo_i, coo_i);
235:   VecSetPreallocationCOO(x, ncoo, coo_i);
236:   return 0;
237: }

239: /*@
240:    VecSetValuesCOO - set values at once in a vector preallocated using `VecSetPreallocationCOO()`

242:    Collective

244:    Input Parameters:
245: +  x - vector being set
246: .  coo_v - the value array
247: -  imode - the insert mode

249:    Level: beginner

251:    Note:
252:    The values must follow the order of the indices prescribed with `VecSetPreallocationCOO()` or `VecSetPreallocationCOOLocal()`.
253:    When repeated entries are specified in the COO indices the coo_v values are first properly summed, regardless of the value of imode.
254:    The imode flag indicates if coo_v must be added to the current values of the vector (`ADD_VALUES`) or overwritten (`INSERT_VALUES`).
255:    `VecAssemblyBegin()` and `VecAssemblyEnd()` do not need to be called after this routine. It automatically handles the assembly process.

257: .seealso: [](chapter_vectors), `Vec`, VecSetPreallocationCOO(), VecSetPreallocationCOOLocal(), VecSetValues()
258: @*/
259: PetscErrorCode VecSetValuesCOO(Vec x, const PetscScalar coo_v[], InsertMode imode)
260: {
264:   PetscLogEventBegin(VEC_SetValuesCOO, x, 0, 0, 0);
265:   if (x->ops->setvaluescoo) {
266:     PetscUseTypeMethod(x, setvaluescoo, coo_v, imode);
267:     PetscObjectStateIncrease((PetscObject)x);
268:   } else {
269:     IS              is_coo_i;
270:     const PetscInt *coo_i;
271:     PetscInt        ncoo;
272:     PetscMemType    mtype;

274:     PetscGetMemType(coo_v, &mtype);
276:     PetscObjectQuery((PetscObject)x, "__PETSc_coo_i", (PetscObject *)&is_coo_i);
278:     ISGetLocalSize(is_coo_i, &ncoo);
279:     ISGetIndices(is_coo_i, &coo_i);
280:     if (imode != ADD_VALUES) VecZeroEntries(x);
281:     VecSetValues(x, ncoo, coo_i, coo_v, ADD_VALUES);
282:     ISRestoreIndices(is_coo_i, &coo_i);
283:     VecAssemblyBegin(x);
284:     VecAssemblyEnd(x);
285:   }
286:   PetscLogEventEnd(VEC_SetValuesCOO, x, 0, 0, 0);
287:   return 0;
288: }

290: static PetscErrorCode VecPointwiseApply_Private(Vec w, Vec x, Vec y, PetscLogEvent event, PetscErrorCode (*const pointwise_op)(Vec, Vec, Vec))
291: {
300:   VecCheckSameSize(w, 1, x, 2);
301:   VecCheckSameSize(w, 1, y, 3);
302:   VecSetErrorIfLocked(w, 1);

305:   if (event) PetscLogEventBegin(event, x, y, w, 0);
306:   (*pointwise_op)(w, x, y);
307:   if (event) PetscLogEventEnd(event, x, y, w, 0);
308:   PetscObjectStateIncrease((PetscObject)w);
309:   return 0;
310: }

312: /*@
313:    VecPointwiseMax - Computes the component-wise maximum `w[i] = max(x[i], y[i])`.

315:    Logically Collective

317:    Input Parameters:
318: +  x - the first input vector
319: -  y - the second input vector

321:    Output Parameter:
322: .  w - the result

324:    Level: advanced

326:    Notes:
327:    Any subset of the `x`, `y`, and `w` may be the same vector.

329:    For complex numbers compares only the real part

331: .seealso: [](chapter_vectors), `Vec`, `VecPointwiseDivide()`, `VecPointwiseMult()`, `VecPointwiseMin()`, `VecPointwiseMaxAbs()`, `VecMaxPointwiseDivide()`
332: @*/
333: PetscErrorCode VecPointwiseMax(Vec w, Vec x, Vec y)
334: {
336:   // REVIEW ME: no log event?
337:   VecPointwiseApply_Private(w, x, y, 0, w->ops->pointwisemax);
338:   return 0;
339: }

341: /*@
342:    VecPointwiseMin - Computes the component-wise minimum `w[i] = min(x[i], y[i])`.

344:    Logically Collective

346:    Input Parameters:
347: +  x - the first input vector
348: -  y - the second input vector

350:    Output Parameter:
351: .  w - the result

353:    Level: advanced

355:    Notes:
356:    Any subset of the `x`, `y`, and `w` may be the same vector.

358:    For complex numbers compares only the real part

360: .seealso: [](chapter_vectors), `Vec`, `VecPointwiseDivide()`, `VecPointwiseMult()`, `VecPointwiseMin()`, `VecPointwiseMaxAbs()`, `VecMaxPointwiseDivide()`
361: @*/
362: PetscErrorCode VecPointwiseMin(Vec w, Vec x, Vec y)
363: {
365:   // REVIEW ME: no log event?
366:   VecPointwiseApply_Private(w, x, y, 0, w->ops->pointwisemin);
367:   return 0;
368: }

370: /*@
371:    VecPointwiseMaxAbs - Computes the component-wise maximum of the absolute values `w[i] = max(abs(x[i]), abs(y[i]))`.

373:    Logically Collective

375:    Input Parameters:
376: +  x - the first input vector
377: -  y - the second input vector

379:    Output Parameter:
380: .  w - the result

382:    Level: advanced

384:    Notes:
385:    Any subset of the `x`, `y`, and `w` may be the same vector.

387: .seealso: [](chapter_vectors), `Vec`, `VecPointwiseDivide()`, `VecPointwiseMult()`, `VecPointwiseMin()`, `VecPointwiseMax()`, `VecMaxPointwiseDivide()`
388: @*/
389: PetscErrorCode VecPointwiseMaxAbs(Vec w, Vec x, Vec y)
390: {
392:   // REVIEW ME: no log event?
393:   VecPointwiseApply_Private(w, x, y, 0, w->ops->pointwisemaxabs);
394:   return 0;
395: }

397: /*@
398:    VecPointwiseDivide - Computes the component-wise division `w[i] = x[i] / y[i]`.

400:    Logically Collective

402:    Input Parameters:
403: +  x - the numerator vector
404: -  y - the denominator vector

406:    Output Parameter:
407: .  w - the result

409:    Level: advanced

411:    Note:
412:    Any subset of the `x`, `y`, and `w` may be the same vector.

414: .seealso: [](chapter_vectors), `Vec`, `VecPointwiseMult()`, `VecPointwiseMax()`, `VecPointwiseMin()`, `VecPointwiseMaxAbs()`, `VecMaxPointwiseDivide()`
415: @*/
416: PetscErrorCode VecPointwiseDivide(Vec w, Vec x, Vec y)
417: {
419:   // REVIEW ME: no log event?
420:   VecPointwiseApply_Private(w, x, y, 0, w->ops->pointwisedivide);
421:   return 0;
422: }

424: /*@
425:    VecPointwiseMult - Computes the component-wise multiplication `w[i] = x[i] * y[i]`.

427:    Logically Collective

429:    Input Parameters:
430: .  x, y  - the vectors

432:    Output Parameter:
433: .  w - the result

435:    Level: advanced

437:    Note:
438:    Any subset of the `x`, `y`, and `w` may be the same vector.

440: .seealso: [](chapter_vectors), `Vec`, `VecPointwiseDivide()`, `VecPointwiseMax()`, `VecPointwiseMin()`, `VecPointwiseMaxAbs()`, `VecMaxPointwiseDivide()`
441: @*/
442: PetscErrorCode VecPointwiseMult(Vec w, Vec x, Vec y)
443: {
445:   VecPointwiseApply_Private(w, x, y, VEC_PointwiseMult, w->ops->pointwisemult);
446:   return 0;
447: }

449: /*@
450:    VecDuplicate - Creates a new vector of the same type as an existing vector.

452:    Collective

454:    Input Parameters:
455: .  v - a vector to mimic

457:    Output Parameter:
458: .  newv - location to put new vector

460:    Level: beginner

462:    Notes:
463:    VecDuplicate() DOES NOT COPY the vector entries, but rather allocates storage
464:    for the new vector.  Use `VecCopy()` to copy a vector.

466:    Use `VecDestroy()` to free the space. Use `VecDuplicateVecs()` to get several
467:    vectors.

469: .seealso: [](chapter_vectors), `Vec`, `VecDestroy()`, `VecDuplicateVecs()`, `VecCreate()`, `VecCopy()`
470: @*/
471: PetscErrorCode VecDuplicate(Vec v, Vec *newv)
472: {
476:   PetscUseTypeMethod(v, duplicate, newv);
477: #if PetscDefined(HAVE_DEVICE)
478:   if (v->boundtocpu && v->bindingpropagates) {
479:     VecSetBindingPropagates(*newv, PETSC_TRUE);
480:     VecBindToCPU(*newv, PETSC_TRUE);
481:   }
482: #endif
483:   PetscObjectStateIncrease((PetscObject)(*newv));
484:   return 0;
485: }

487: /*@C
488:    VecDestroy - Destroys a vector.

490:    Collective

492:    Input Parameters:
493: .  v  - the vector

495:    Level: beginner

497: .seealso: [](chapter_vectors), `Vec`, `VecDuplicate()`, `VecDestroyVecs()`
498: @*/
499: PetscErrorCode VecDestroy(Vec *v)
500: {
502:   if (!*v) return 0;
504:   if (--((PetscObject)(*v))->refct > 0) {
505:     *v = NULL;
506:     return 0;
507:   }

509:   PetscObjectSAWsViewOff((PetscObject)*v);
510:   /* destroy the internal part */
511:   PetscTryTypeMethod(*v, destroy);
512:   PetscFree((*v)->defaultrandtype);
513:   /* destroy the external/common part */
514:   PetscLayoutDestroy(&(*v)->map);
515:   PetscHeaderDestroy(v);
516:   return 0;
517: }

519: /*@C
520:    VecDuplicateVecs - Creates several vectors of the same type as an existing vector.

522:    Collective

524:    Input Parameters:
525: +  m - the number of vectors to obtain
526: -  v - a vector to mimic

528:    Output Parameter:
529: .  V - location to put pointer to array of vectors

531:    Level: intermediate

533:    Note:
534:    Use `VecDestroyVecs()` to free the space. Use `VecDuplicate()` to form a single
535:    vector.

537:    Fortran Note:
538:    The Fortran interface is slightly different from that given below, it
539:    requires one to pass in V a `Vec` array of size at least m.
540:    See the [](chapter_fortran) for details.

542: .seealso: [](chapter_vectors), `Vec`, [](chapter_fortran), `VecDestroyVecs()`, `VecDuplicate()`, `VecCreate()`, `VecDuplicateVecsF90()`
543: @*/
544: PetscErrorCode VecDuplicateVecs(Vec v, PetscInt m, Vec *V[])
545: {
549:   PetscUseTypeMethod(v, duplicatevecs, m, V);
550: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_CUDA)
551:   if (v->boundtocpu && v->bindingpropagates) {
552:     PetscInt i;

554:     for (i = 0; i < m; i++) {
555:       /* Since ops->duplicatevecs might itself propagate the value of boundtocpu,
556:        * avoid unnecessary overhead by only calling VecBindToCPU() if the vector isn't already bound. */
557:       if (!(*V)[i]->boundtocpu) {
558:         VecSetBindingPropagates((*V)[i], PETSC_TRUE);
559:         VecBindToCPU((*V)[i], PETSC_TRUE);
560:       }
561:     }
562:   }
563: #endif
564:   return 0;
565: }

567: /*@C
568:    VecDestroyVecs - Frees a block of vectors obtained with `VecDuplicateVecs()`.

570:    Collective

572:    Input Parameters:
573: +  vv - pointer to pointer to array of vector pointers, if `NULL` no vectors are destroyed
574: -  m - the number of vectors previously obtained, if zero no vectors are destroyed

576:    Level: intermediate

578:    Fortran Note:
579:    The Fortran interface is slightly different from that given below.
580:    See the [](chapter_fortran) for details.

582: .seealso: [](chapter_vectors), `Vec`, [](chapter_fortran), `VecDuplicateVecs()`, `VecDestroyVecsf90()`
583: @*/
584: PetscErrorCode VecDestroyVecs(PetscInt m, Vec *vv[])
585: {
588:   if (!m || !*vv) {
589:     *vv = NULL;
590:     return 0;
591:   }
594:   (*(**vv)->ops->destroyvecs)(m, *vv);
595:   *vv = NULL;
596:   return 0;
597: }

599: /*@C
600:    VecViewFromOptions - View a vector based on values in the options database

602:    Collective

604:    Input Parameters:
605: +  A - the vector
606: .  obj - Optional object that provides the options prefix for this viewing
607: -  name - command line option

609:    Level: intermediate

611: .seealso: [](chapter_vectors), `Vec`, `VecView`, `PetscObjectViewFromOptions()`, `VecCreate()`
612: @*/
613: PetscErrorCode VecViewFromOptions(Vec A, PetscObject obj, const char name[])
614: {
616:   PetscObjectViewFromOptions((PetscObject)A, obj, name);
617:   return 0;
618: }

620: /*@C
621:    VecView - Views a vector object.

623:    Collective

625:    Input Parameters:
626: +  vec - the vector
627: -  viewer - an optional visualization context

629:    Level: beginner

631:    Notes:
632:    The available visualization contexts include
633: +     `PETSC_VIEWER_STDOUT_SELF` - for sequential vectors
634: .     `PETSC_VIEWER_STDOUT_WORLD` - for parallel vectors created on `PETSC_COMM_WORLD`
635: -     `PETSC_VIEWER_STDOUT`_(comm) - for parallel vectors created on MPI communicator comm

637:    You can change the format the vector is printed using the
638:    option `PetscViewerPushFormat()`.

640:    The user can open alternative viewers with
641: +    `PetscViewerASCIIOpen()` - Outputs vector to a specified file
642: .    `PetscViewerBinaryOpen()` - Outputs vector in binary to a
643:          specified file; corresponding input uses `VecLoad()`
644: .    `PetscViewerDrawOpen()` - Outputs vector to an X window display
645: .    `PetscViewerSocketOpen()` - Outputs vector to Socket viewer
646: -    `PetscViewerHDF5Open()` - Outputs vector to HDF5 file viewer

648:    The user can call `PetscViewerPushFormat()` to specify the output
649:    format of ASCII printed objects (when using `PETSC_VIEWER_STDOUT_SELF`,
650:    `PETSC_VIEWER_STDOUT_WORLD` and `PetscViewerASCIIOpen()`).  Available formats include
651: +    `PETSC_VIEWER_DEFAULT` - default, prints vector contents
652: .    `PETSC_VIEWER_ASCII_MATLAB` - prints vector contents in MATLAB format
653: .    `PETSC_VIEWER_ASCII_INDEX` - prints vector contents, including indices of vector elements
654: -    `PETSC_VIEWER_ASCII_COMMON` - prints vector contents, using a
655:          format common among all vector types

657:     You can pass any number of vector objects, or other PETSc objects to the same viewer.

659:     In the debugger you can do call `VecView`(v,0) to display the vector. (The same holds for any PETSc object viewer).

661:    Notes for binary viewer:
662:      If you pass multiple vectors to a binary viewer you can read them back in in the same order
663:      with `VecLoad()`.

665:      If the blocksize of the vector is greater than one then you must provide a unique prefix to
666:      the vector with `PetscObjectSetOptionsPrefix`((`PetscObject`)vec,"uniqueprefix"); BEFORE calling `VecView()` on the
667:      vector to be stored and then set that same unique prefix on the vector that you pass to `VecLoad()`. The blocksize
668:      information is stored in an ASCII file with the same name as the binary file plus a ".info" appended to the
669:      filename. If you copy the binary file, make sure you copy the associated .info file with it.

671:      See the manual page for `VecLoad()` on the exact format the binary viewer stores
672:      the values in the file.

674:    Notes for HDF5 Viewer:
675:      The name of the `Vec` (given with `PetscObjectSetName()` is the name that is used
676:      for the object in the HDF5 file. If you wish to store the same Vec into multiple
677:      datasets in the same file (typically with different values), you must change its
678:      name each time before calling the `VecView()`. To load the same vector,
679:      the name of the Vec object passed to `VecLoad()` must be the same.

681:      If the block size of the vector is greater than 1 then it is used as the first dimension in the HDF5 array.
682:      If the function `PetscViewerHDF5SetBaseDimension2()`is called then even if the block size is one it will
683:      be used as the first dimension in the HDF5 array (that is the HDF5 array will always be two dimensional)
684:      See also `PetscViewerHDF5SetTimestep()` which adds an additional complication to reading and writing `Vec`
685:      with the HDF5 viewer.

687: .seealso: [](chapter_vectors), `Vec`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscDrawLGCreate()`,
688:           `PetscViewerSocketOpen()`, `PetscViewerBinaryOpen()`, `VecLoad()`, `PetscViewerCreate()`,
689:           `PetscRealView()`, `PetscScalarView()`, `PetscIntView()`, `PetscViewerHDF5SetTimestep()`
690: @*/
691: PetscErrorCode VecView(Vec vec, PetscViewer viewer)
692: {
693:   PetscBool         iascii;
694:   PetscViewerFormat format;
695:   PetscMPIInt       size;

699:   if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)vec), &viewer);
701:   PetscViewerGetFormat(viewer, &format);
702:   MPI_Comm_size(PetscObjectComm((PetscObject)vec), &size);
703:   if (size == 1 && format == PETSC_VIEWER_LOAD_BALANCE) return 0;


707:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &iascii);
708:   if (iascii) {
709:     PetscInt rows, bs;

711:     PetscObjectPrintClassNamePrefixType((PetscObject)vec, viewer);
712:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
713:       PetscViewerASCIIPushTab(viewer);
714:       VecGetSize(vec, &rows);
715:       VecGetBlockSize(vec, &bs);
716:       if (bs != 1) {
717:         PetscViewerASCIIPrintf(viewer, "length=%" PetscInt_FMT ", bs=%" PetscInt_FMT "\n", rows, bs);
718:       } else {
719:         PetscViewerASCIIPrintf(viewer, "length=%" PetscInt_FMT "\n", rows);
720:       }
721:       PetscViewerASCIIPopTab(viewer);
722:     }
723:   }
724:   VecLockReadPush(vec);
725:   PetscLogEventBegin(VEC_View, vec, viewer, 0, 0);
726:   if ((format == PETSC_VIEWER_NATIVE || format == PETSC_VIEWER_LOAD_BALANCE) && vec->ops->viewnative) {
727:     PetscUseTypeMethod(vec, viewnative, viewer);
728:   } else {
729:     PetscUseTypeMethod(vec, view, viewer);
730:   }
731:   VecLockReadPop(vec);
732:   PetscLogEventEnd(VEC_View, vec, viewer, 0, 0);
733:   return 0;
734: }

736: #if defined(PETSC_USE_DEBUG)
737: #include <../src/sys/totalview/tv_data_display.h>
738: PETSC_UNUSED static int TV_display_type(const struct _p_Vec *v)
739: {
740:   const PetscScalar *values;
741:   char               type[32];

743:   TV_add_row("Local rows", "int", &v->map->n);
744:   TV_add_row("Global rows", "int", &v->map->N);
745:   TV_add_row("Typename", TV_ascii_string_type, ((PetscObject)v)->type_name);
746:   VecGetArrayRead((Vec)v, &values);
747:   PetscSNPrintf(type, 32, "double[%" PetscInt_FMT "]", v->map->n);
748:   TV_add_row("values", type, values);
749:   VecRestoreArrayRead((Vec)v, &values);
750:   return TV_format_OK;
751: }
752: #endif

754: /*@C
755:    VecViewNative - Views a vector object with the original type specific viewer

757:    Collective

759:    Input Parameters:
760: +  vec - the vector
761: -  viewer - an optional visualization context

763:    Level: developer

765: .seealso: [](chapter_vectors), `Vec`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscDrawLGCreate()`, `VecView()`
766:           `PetscViewerSocketOpen()`, `PetscViewerBinaryOpen()`, `VecLoad()`, `PetscViewerCreate()`,
767:           `PetscRealView()`, `PetscScalarView()`, `PetscIntView()`, `PetscViewerHDF5SetTimestep()`
768: @*/
769: PetscErrorCode VecViewNative(Vec vec, PetscViewer viewer)
770: {
773:   if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)vec), &viewer);
775:   PetscUseTypeMethod(vec, viewnative, viewer);
776:   return 0;
777: }

779: /*@
780:    VecGetSize - Returns the global number of elements of the vector.

782:    Not Collective

784:    Input Parameter:
785: .  x - the vector

787:    Output Parameters:
788: .  size - the global length of the vector

790:    Level: beginner

792: .seealso: [](chapter_vectors), `Vec`, `VecGetLocalSize()`
793: @*/
794: PetscErrorCode VecGetSize(Vec x, PetscInt *size)
795: {
799:   PetscUseTypeMethod(x, getsize, size);
800:   return 0;
801: }

803: /*@
804:    VecGetLocalSize - Returns the number of elements of the vector stored
805:    in local memory.

807:    Not Collective

809:    Input Parameter:
810: .  x - the vector

812:    Output Parameter:
813: .  size - the length of the local piece of the vector

815:    Level: beginner

817: .seealso: [](chapter_vectors), `Vec`, `VecGetSize()`
818: @*/
819: PetscErrorCode VecGetLocalSize(Vec x, PetscInt *size)
820: {
824:   PetscUseTypeMethod(x, getlocalsize, size);
825:   return 0;
826: }

828: /*@C
829:    VecGetOwnershipRange - Returns the range of indices owned by
830:    this processor, assuming that the vectors are laid out with the
831:    first n1 elements on the first processor, next n2 elements on the
832:    second, etc.  For certain parallel layouts this range may not be
833:    well defined.

835:    Not Collective

837:    Input Parameter:
838: .  x - the vector

840:    Output Parameters:
841: +  low - the first local element, pass in `NULL` if not interested
842: -  high - one more than the last local element, pass in `NULL` if not interested

844:    Level: beginner

846:    Note:
847:    The high argument is one more than the last element stored locally.

849:    Fortran Note:
850:    `PETSC_NULL_INTEGER` should be used instead of NULL

852: .seealso: [](chapter_vectors), `Vec`, `MatGetOwnershipRange()`, `MatGetOwnershipRanges()`, `VecGetOwnershipRanges()`
853: @*/
854: PetscErrorCode VecGetOwnershipRange(Vec x, PetscInt *low, PetscInt *high)
855: {
860:   if (low) *low = x->map->rstart;
861:   if (high) *high = x->map->rend;
862:   return 0;
863: }

865: /*@C
866:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor,
867:    assuming that the vectors are laid out with the
868:    first n1 elements on the first processor, next n2 elements on the
869:    second, etc.  For certain parallel layouts this range may not be
870:    well defined.

872:    Not Collective

874:    Input Parameter:
875: .  x - the vector

877:    Output Parameters:
878: .  range - array of length size+1 with the start and end+1 for each process

880:    Level: beginner

882:    Notes:
883:    The high argument is one more than the last element stored locally.

885:    If the ranges are used after all vectors that share the ranges has been destroyed then the program will crash accessing ranges[].

887:    Fortran Note:
888:    You must PASS in an array of length size+1

890: .seealso: [](chapter_vectors), `Vec`, `MatGetOwnershipRange()`, `MatGetOwnershipRanges()`, `VecGetOwnershipRange()`
891: @*/
892: PetscErrorCode VecGetOwnershipRanges(Vec x, const PetscInt *ranges[])
893: {
896:   PetscLayoutGetRanges(x->map, ranges);
897:   return 0;
898: }

900: /*@
901:    VecSetOption - Sets an option for controlling a vector's behavior.

903:    Collective

905:    Input Parameters:
906: +  x - the vector
907: .  op - the option
908: -  flag - turn the option on or off

910:    Supported Options:
911: +     `VEC_IGNORE_OFF_PROC_ENTRIES`, which causes `VecSetValues()` to ignore
912:           entries destined to be stored on a separate processor. This can be used
913:           to eliminate the global reduction in the `VecAssemblyBegin()` if you know
914:           that you have only used `VecSetValues()` to set local elements
915: .     `VEC_IGNORE_NEGATIVE_INDICES`, which means you can pass negative indices
916:           in ix in calls to `VecSetValues()` or `VecGetValues()`. These rows are simply
917:           ignored.
918: -     `VEC_SUBSET_OFF_PROC_ENTRIES`, which causes `VecAssemblyBegin()` to assume that the off-process
919:           entries will always be a subset (possibly equal) of the off-process entries set on the
920:           first assembly which had a true `VEC_SUBSET_OFF_PROC_ENTRIES` and the vector has not
921:           changed this flag afterwards. If this assembly is not such first assembly, then this
922:           assembly can reuse the communication pattern setup in that first assembly, thus avoiding
923:           a global reduction. Subsequent assemblies setting off-process values should use the same
924:           InsertMode as the first assembly.

926:    Level: intermediate

928:    Developer Note:
929:    The `InsertMode` restriction could be removed by packing the stash messages out of place.

931: .seealso: [](chapter_vectors), `Vec`, `VecSetValues()`
932: @*/
933: PetscErrorCode VecSetOption(Vec x, VecOption op, PetscBool flag)
934: {
937:   PetscTryTypeMethod(x, setoption, op, flag);
938:   return 0;
939: }

941: /* Default routines for obtaining and releasing; */
942: /* may be used by any implementation */
943: PetscErrorCode VecDuplicateVecs_Default(Vec w, PetscInt m, Vec *V[])
944: {
948:   PetscMalloc1(m, V);
949:   for (PetscInt i = 0; i < m; i++) VecDuplicate(w, *V + i);
950:   return 0;
951: }

953: PetscErrorCode VecDestroyVecs_Default(PetscInt m, Vec v[])
954: {
955:   PetscInt i;

958:   for (i = 0; i < m; i++) VecDestroy(&v[i]);
959:   PetscFree(v);
960:   return 0;
961: }

963: /*@
964:    VecResetArray - Resets a vector to use its default memory. Call this
965:    after the use of `VecPlaceArray()`.

967:    Not Collective

969:    Input Parameters:
970: .  vec - the vector

972:    Level: developer

974: .seealso: [](chapter_vectors), `Vec`, `VecGetArray()`, `VecRestoreArray()`, `VecReplaceArray()`, `VecPlaceArray()`
975: @*/
976: PetscErrorCode VecResetArray(Vec vec)
977: {
980:   PetscUseTypeMethod(vec, resetarray);
981:   PetscObjectStateIncrease((PetscObject)vec);
982:   return 0;
983: }

985: /*@C
986:   VecLoad - Loads a vector that has been stored in binary or HDF5 format
987:   with `VecView()`.

989:   Collective

991:   Input Parameters:
992: + vec - the newly loaded vector, this needs to have been created with `VecCreate()` or
993:            some related function before a call to VecLoad().
994: - viewer - binary file viewer, obtained from PetscViewerBinaryOpen() or
995:            HDF5 file viewer, obtained from PetscViewerHDF5Open()

997:    Level: intermediate

999:   Notes:
1000:   Defaults to the standard Seq or MPI Vec, if you want some other type of `Vec` call `VecSetFromOptions()`
1001:   before calling this.

1003:   The input file must contain the full global vector, as
1004:   written by the routine `VecView()`.

1006:   If the type or size of vec is not set before a call to `VecLoad()`, PETSc
1007:   sets the type and the local and global sizes. If type and/or
1008:   sizes are already set, then the same are used.

1010:   If using the binary viewer and the blocksize of the vector is greater than one then you must provide a unique prefix to
1011:   the vector with `PetscObjectSetOptionsPrefix`((`PetscObject`)vec,"uniqueprefix"); BEFORE calling `VecView()` on the
1012:   vector to be stored and then set that same unique prefix on the vector that you pass to VecLoad(). The blocksize
1013:   information is stored in an ASCII file with the same name as the binary file plus a ".info" appended to the
1014:   filename. If you copy the binary file, make sure you copy the associated .info file with it.

1016:   If using HDF5, you must assign the Vec the same name as was used in the Vec
1017:   that was stored in the file using `PetscObjectSetName(). Otherwise you will
1018:   get the error message: "Cannot H5DOpen2() with `Vec` name NAMEOFOBJECT".

1020:   If the HDF5 file contains a two dimensional array the first dimension is treated as the block size
1021:   in loading the vector. Hence, for example, using MATLAB notation h5create('vector.dat','/Test_Vec',[27 1]);
1022:   will load a vector of size 27 and block size 27 thus resulting in all 27 entries being on the first process of
1023:   vectors communicator and the rest of the processes having zero entries

1025:   Notes for advanced users when using the binary viewer:
1026:   Most users should not need to know the details of the binary storage
1027:   format, since `VecLoad()` and `VecView()` completely hide these details.
1028:   But for anyone who's interested, the standard binary vector storage
1029:   format is
1030: .vb
1031:      PetscInt    VEC_FILE_CLASSID
1032:      PetscInt    number of rows
1033:      PetscScalar *values of all entries
1034: .ve

1036:    In addition, PETSc automatically uses byte swapping to work on all machines; the files
1037:    are written ALWAYS using big-endian ordering. On small-endian machines the numbers
1038:    are converted to the small-endian format when they are read in from the file.
1039:    See PetscBinaryRead() and PetscBinaryWrite() to see how this may be done.

1041: .seealso: [](chapter_vectors), `Vec`, `PetscViewerBinaryOpen()`, `VecView()`, `MatLoad()`, `VecLoad()`
1042: @*/
1043: PetscErrorCode VecLoad(Vec vec, PetscViewer viewer)
1044: {
1045:   PetscBool         isbinary, ishdf5, isadios, isexodusii;
1046:   PetscViewerFormat format;

1051:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERBINARY, &isbinary);
1052:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERHDF5, &ishdf5);
1053:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERADIOS, &isadios);
1054:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWEREXODUSII, &isexodusii);

1057:   VecSetErrorIfLocked(vec, 1);
1058:   if (!((PetscObject)vec)->type_name && !vec->ops->create) VecSetType(vec, VECSTANDARD);
1059:   PetscLogEventBegin(VEC_Load, viewer, 0, 0, 0);
1060:   PetscViewerGetFormat(viewer, &format);
1061:   if (format == PETSC_VIEWER_NATIVE && vec->ops->loadnative) {
1062:     PetscUseTypeMethod(vec, loadnative, viewer);
1063:   } else {
1064:     PetscUseTypeMethod(vec, load, viewer);
1065:   }
1066:   PetscLogEventEnd(VEC_Load, viewer, 0, 0, 0);
1067:   return 0;
1068: }

1070: /*@
1071:    VecReciprocal - Replaces each component of a vector by its reciprocal.

1073:    Logically Collective

1075:    Input Parameter:
1076: .  vec - the vector

1078:    Output Parameter:
1079: .  vec - the vector reciprocal

1081:    Level: intermediate

1083: .seealso: [](chapter_vectors), `Vec`, `VecLog()`, `VecExp()`, `VecSqrtAbs()`
1084: @*/
1085: PetscErrorCode VecReciprocal(Vec vec)
1086: {
1090:   VecSetErrorIfLocked(vec, 1);
1091:   PetscUseTypeMethod(vec, reciprocal);
1092:   PetscObjectStateIncrease((PetscObject)vec);
1093:   return 0;
1094: }

1096: /*@C
1097:     VecSetOperation - Allows user to set a vector operation.

1099:    Logically Collective; No Fortran Support

1101:     Input Parameters:
1102: +   vec - the vector
1103: .   op - the name of the operation
1104: -   f - the function that provides the operation.

1106:    Level: advanced

1108:     Usage:
1109: .vb
1110:       PetscErrorCode userview(Vec,PetscViewer);
1111:       VecCreateMPI(comm,m,M,&x);
1112:       VecSetOperation(x,VECOP_VIEW,(void(*)(void))userview);
1113: .ve

1115:     Notes:
1116:     See the file include/petscvec.h for a complete list of matrix
1117:     operations, which all have the form VECOP_<OPERATION>, where
1118:     <OPERATION> is the name (in all capital letters) of the
1119:     user interface routine (e.g., VecView() -> VECOP_VIEW).

1121: .seealso: [](chapter_vectors), `Vec`, `VecCreate()`, `MatShellSetOperation()`
1122: @*/
1123: PetscErrorCode VecSetOperation(Vec vec, VecOperation op, void (*f)(void))
1124: {
1126:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
1127:     vec->ops->viewnative = vec->ops->view;
1128:   } else if (op == VECOP_LOAD && !vec->ops->loadnative) {
1129:     vec->ops->loadnative = vec->ops->load;
1130:   }
1131:   (((void (**)(void))vec->ops)[(int)op]) = f;
1132:   return 0;
1133: }

1135: /*@
1136:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1137:    used during the assembly process to store values that belong to
1138:    other processors.

1140:    Not Collective, different processes can have different size stashes

1142:    Input Parameters:
1143: +  vec   - the vector
1144: .  size  - the initial size of the stash.
1145: -  bsize - the initial size of the block-stash(if used).

1147:    Options Database Keys:
1148: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1149: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1151:    Level: intermediate

1153:    Notes:
1154:      The block-stash is used for values set with `VecSetValuesBlocked()` while
1155:      the stash is used for values set with `VecSetValues()`

1157:      Run with the option -info and look for output of the form
1158:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
1159:      to determine the appropriate value, MM, to use for size and
1160:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
1161:      to determine the value, BMM to use for bsize

1163: .seealso: [](chapter_vectors), `Vec`, `VecSetBlockSize()`, `VecSetValues()`, `VecSetValuesBlocked()`, `VecStashView()`
1164: @*/
1165: PetscErrorCode VecStashSetInitialSize(Vec vec, PetscInt size, PetscInt bsize)
1166: {
1168:   VecStashSetInitialSize_Private(&vec->stash, size);
1169:   VecStashSetInitialSize_Private(&vec->bstash, bsize);
1170:   return 0;
1171: }

1173: /*@
1174:    VecConjugate - Conjugates a vector.

1176:    Logically Collective

1178:    Input Parameters:
1179: .  x - the vector

1181:    Level: intermediate

1183: .seealso: [](chapter_vectors), `Vec`, `VecSet()`
1184: @*/
1185: PetscErrorCode VecConjugate(Vec x)
1186: {
1190:   VecSetErrorIfLocked(x, 1);
1191:   if (PetscDefined(USE_COMPLEX)) {
1192:     PetscUseTypeMethod(x, conjugate);
1193:     /* we need to copy norms here */
1194:     PetscObjectStateIncrease((PetscObject)x);
1195:   }
1196:   return 0;
1197: }

1199: /*@
1200:    VecSetRandom - Sets all components of a vector to random numbers.

1202:    Logically Collective

1204:    Input Parameters:
1205: +  x  - the vector
1206: -  rctx - the random number context, formed by PetscRandomCreate(), or NULL and
1207:           it will create one internally.

1209:    Output Parameter:
1210: .  x  - the vector

1212:    Example of Usage:
1213: .vb
1214:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1215:      VecSetRandom(x,rctx);
1216:      PetscRandomDestroy(&rctx);
1217: .ve

1219:    Level: intermediate

1221: .seealso: [](chapter_vectors), `Vec`, `VecSet()`, `VecSetValues()`, `PetscRandomCreate()`, `PetscRandomDestroy()`
1222: @*/
1223: PetscErrorCode VecSetRandom(Vec x, PetscRandom rctx)
1224: {
1225:   PetscRandom randObj = NULL;

1231:   VecSetErrorIfLocked(x, 1);

1233:   if (!rctx) {
1234:     PetscRandomCreate(PetscObjectComm((PetscObject)x), &randObj);
1235:     PetscRandomSetType(randObj, x->defaultrandtype);
1236:     PetscRandomSetFromOptions(randObj);
1237:     rctx = randObj;
1238:   }

1240:   PetscLogEventBegin(VEC_SetRandom, x, rctx, 0, 0);
1241:   PetscUseTypeMethod(x, setrandom, rctx);
1242:   PetscLogEventEnd(VEC_SetRandom, x, rctx, 0, 0);

1244:   PetscRandomDestroy(&randObj);
1245:   PetscObjectStateIncrease((PetscObject)x);
1246:   return 0;
1247: }

1249: /*@
1250:   VecZeroEntries - puts a `0.0` in each element of a vector

1252:   Logically Collective

1254:   Input Parameter:
1255: . vec - The vector

1257:   Level: beginner

1259: .seealso: [](chapter_vectors), `Vec`, `VecCreate()`, `VecSetOptionsPrefix()`, `VecSet()`, `VecSetValues()`
1260: @*/
1261: PetscErrorCode VecZeroEntries(Vec vec)
1262: {
1263:   VecSet(vec, 0);
1264:   return 0;
1265: }

1267: /*
1268:   VecSetTypeFromOptions_Private - Sets the type of vector from user options. Defaults to a PETSc sequential vector on one
1269:   processor and a PETSc MPI vector on more than one processor.

1271:   Collective

1273:   Input Parameter:
1274: . vec - The vector

1276:   Level: intermediate

1278: .seealso: [](chapter_vectors), `Vec`, `VecSetFromOptions()`, `VecSetType()`
1279: */
1280: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec, PetscOptionItems *PetscOptionsObject)
1281: {
1282:   PetscBool   opt;
1283:   VecType     defaultType;
1284:   char        typeName[256];
1285:   PetscMPIInt size;

1287:   if (((PetscObject)vec)->type_name) defaultType = ((PetscObject)vec)->type_name;
1288:   else {
1289:     MPI_Comm_size(PetscObjectComm((PetscObject)vec), &size);
1290:     if (size > 1) defaultType = VECMPI;
1291:     else defaultType = VECSEQ;
1292:   }

1294:   VecRegisterAll();
1295:   PetscOptionsFList("-vec_type", "Vector type", "VecSetType", VecList, defaultType, typeName, 256, &opt);
1296:   if (opt) {
1297:     VecSetType(vec, typeName);
1298:   } else {
1299:     VecSetType(vec, defaultType);
1300:   }
1301:   return 0;
1302: }

1304: /*@
1305:   VecSetFromOptions - Configures the vector from the options database.

1307:   Collective

1309:   Input Parameter:
1310: . vec - The vector

1312:   Level: beginner

1314:   Notes:
1315:   To see all options, run your program with the -help option, or consult the users manual.

1317:   Must be called after `VecCreate()` but before the vector is used.

1319: .seealso: [](chapter_vectors), `Vec`, `VecCreate()`, `VecSetOptionsPrefix()`
1320: @*/
1321: PetscErrorCode VecSetFromOptions(Vec vec)
1322: {
1323:   PetscBool flg;
1324:   PetscInt  bind_below = 0;


1328:   PetscObjectOptionsBegin((PetscObject)vec);
1329:   /* Handle vector type options */
1330:   VecSetTypeFromOptions_Private(vec, PetscOptionsObject);

1332:   /* Handle specific vector options */
1333:   PetscTryTypeMethod(vec, setfromoptions, PetscOptionsObject);

1335:   /* Bind to CPU if below a user-specified size threshold.
1336:    * This perhaps belongs in the options for the GPU Vec types, but VecBindToCPU() does nothing when called on non-GPU types,
1337:    * and putting it here makes is more maintainable than duplicating this for all. */
1338:   PetscOptionsInt("-vec_bind_below", "Set the size threshold (in local entries) below which the Vec is bound to the CPU", "VecBindToCPU", bind_below, &bind_below, &flg);
1339:   if (flg && vec->map->n < bind_below) VecBindToCPU(vec, PETSC_TRUE);

1341:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
1342:   PetscObjectProcessOptionsHandlers((PetscObject)vec, PetscOptionsObject);
1343:   PetscOptionsEnd();
1344:   return 0;
1345: }

1347: /*@
1348:   VecSetSizes - Sets the local and global sizes, and checks to determine compatibility

1350:   Collective

1352:   Input Parameters:
1353: + v - the vector
1354: . n - the local size (or `PETSC_DECIDE` to have it set)
1355: - N - the global size (or `PETSC_DETERMINE` to have it set)

1357:   Level: intermediate

1359:   Notes:
1360:   N cannot be `PETSC_DETERMINE` if n is `PETSC_DECIDE`

1362:   If one processor calls this with N of `PETSC_DETERMINE` then all processors must, otherwise the program will hang.

1364: .seealso: [](chapter_vectors), `Vec`, `VecGetSize()`, `PetscSplitOwnership()`
1365: @*/
1366: PetscErrorCode VecSetSizes(Vec v, PetscInt n, PetscInt N)
1367: {
1369:   if (N >= 0) {
1372:   }
1374:              v->map->n, v->map->N);
1375:   v->map->n = n;
1376:   v->map->N = N;
1377:   PetscTryTypeMethod(v, create);
1378:   v->ops->create = NULL;
1379:   return 0;
1380: }

1382: /*@
1383:    VecSetBlockSize - Sets the block size for future calls to `VecSetValuesBlocked()`
1384:    and `VecSetValuesBlockedLocal()`.

1386:    Logically Collective

1388:    Input Parameters:
1389: +  v - the vector
1390: -  bs - the blocksize

1392:    Level: advanced

1394:    Note:
1395:    All vectors obtained by `VecDuplicate()` inherit the same blocksize.

1397: .seealso: [](chapter_vectors), `Vec`, `VecSetValuesBlocked()`, `VecSetLocalToGlobalMapping()`, `VecGetBlockSize()`
1398: @*/
1399: PetscErrorCode VecSetBlockSize(Vec v, PetscInt bs)
1400: {
1403:   PetscLayoutSetBlockSize(v->map, bs);
1404:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
1405:   return 0;
1406: }

1408: /*@
1409:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for `VecSetValuesBlocked()`
1410:    and `VecSetValuesBlockedLocal()`.

1412:    Not Collective

1414:    Input Parameter:
1415: .  v - the vector

1417:    Output Parameter:
1418: .  bs - the blocksize

1420:    Level: advanced

1422:    Note:
1423:    All vectors obtained by `VecDuplicate()` inherit the same blocksize.

1425: .seealso: [](chapter_vectors), `Vec`, `VecSetValuesBlocked()`, `VecSetLocalToGlobalMapping()`, `VecSetBlockSize()`
1426: @*/
1427: PetscErrorCode VecGetBlockSize(Vec v, PetscInt *bs)
1428: {
1431:   PetscLayoutGetBlockSize(v->map, bs);
1432:   return 0;
1433: }

1435: /*@C
1436:    VecSetOptionsPrefix - Sets the prefix used for searching for all
1437:    `Vec` options in the database.

1439:    Logically Collective

1441:    Input Parameters:
1442: +  v - the `Vec` context
1443: -  prefix - the prefix to prepend to all option names

1445:    Level: advanced

1447:    Note:
1448:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1449:    The first character of all runtime options is AUTOMATICALLY the hyphen.

1451: .seealso: [](chapter_vectors), `Vec`, `VecSetFromOptions()`
1452: @*/
1453: PetscErrorCode VecSetOptionsPrefix(Vec v, const char prefix[])
1454: {
1456:   PetscObjectSetOptionsPrefix((PetscObject)v, prefix);
1457:   return 0;
1458: }

1460: /*@C
1461:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all
1462:    `Vec` options in the database.

1464:    Logically Collective

1466:    Input Parameters:
1467: +  v - the `Vec` context
1468: -  prefix - the prefix to prepend to all option names

1470:    Level: advanced

1472:    Note:
1473:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1474:    The first character of all runtime options is AUTOMATICALLY the hyphen.

1476: .seealso: [](chapter_vectors), `Vec`, `VecGetOptionsPrefix()`
1477: @*/
1478: PetscErrorCode VecAppendOptionsPrefix(Vec v, const char prefix[])
1479: {
1481:   PetscObjectAppendOptionsPrefix((PetscObject)v, prefix);
1482:   return 0;
1483: }

1485: /*@C
1486:    VecGetOptionsPrefix - Sets the prefix used for searching for all
1487:    Vec options in the database.

1489:    Not Collective

1491:    Input Parameter:
1492: .  v - the `Vec` context

1494:    Output Parameter:
1495: .  prefix - pointer to the prefix string used

1497:    Level: advanced

1499:    Fortran Note:
1500:    The user must pass in a string `prefix` of
1501:    sufficient length to hold the prefix.

1503: .seealso: [](chapter_vectors), `Vec`, `VecAppendOptionsPrefix()`
1504: @*/
1505: PetscErrorCode VecGetOptionsPrefix(Vec v, const char *prefix[])
1506: {
1508:   PetscObjectGetOptionsPrefix((PetscObject)v, prefix);
1509:   return 0;
1510: }

1512: /*@
1513:    VecSetUp - Sets up the internal vector data structures for the later use.

1515:    Collective

1517:    Input Parameters:
1518: .  v - the `Vec` context

1520:    Level: advanced

1522:    Notes:
1523:    For basic use of the `Vec` classes the user need not explicitly call
1524:    `VecSetUp()`, since these actions will happen automatically.

1526: .seealso: [](chapter_vectors), `Vec`, `VecCreate()`, `VecDestroy()`
1527: @*/
1528: PetscErrorCode VecSetUp(Vec v)
1529: {
1530:   PetscMPIInt size;

1534:   if (!((PetscObject)v)->type_name) {
1535:     MPI_Comm_size(PetscObjectComm((PetscObject)v), &size);
1536:     if (size == 1) {
1537:       VecSetType(v, VECSEQ);
1538:     } else {
1539:       VecSetType(v, VECMPI);
1540:     }
1541:   }
1542:   return 0;
1543: }

1545: /*
1546:     These currently expose the PetscScalar/PetscReal in updating the
1547:     cached norm. If we push those down into the implementation these
1548:     will become independent of PetscScalar/PetscReal
1549: */

1551: /*@
1552:    VecCopy - Copies a vector `y = x`

1554:    Logically Collective

1556:    Input Parameter:
1557: .  x - the vector

1559:    Output Parameter:
1560: .  y - the copy

1562:    Level: beginner

1564:    Note:
1565:    For default parallel PETSc vectors, both `x` and `y` must be distributed in
1566:    the same manner; local copies are done.

1568:    Developer Note:
1570:    of the vectors to be sequential and one to be parallel so long as both have the same
1571:    local sizes. This is used in some internal functions in PETSc.

1573: .seealso: [](chapter_vectors), `Vec`, `VecDuplicate()`
1574: @*/
1575: PetscErrorCode VecCopy(Vec x, Vec y)
1576: {
1577:   PetscBool flgs[4];
1578:   PetscReal norms[4] = {0.0, 0.0, 0.0, 0.0};

1584:   if (x == y) return 0;
1585:   VecCheckSameLocalSize(x, 1, y, 2);
1587:   VecSetErrorIfLocked(y, 2);

1589: #if !defined(PETSC_USE_MIXED_PRECISION)
1590:   for (PetscInt i = 0; i < 4; i++) PetscObjectComposedDataGetReal((PetscObject)x, NormIds[i], norms[i], flgs[i]);
1591: #endif

1593:   PetscLogEventBegin(VEC_Copy, x, y, 0, 0);
1594: #if defined(PETSC_USE_MIXED_PRECISION)
1595:   extern PetscErrorCode VecGetArray(Vec, double **);
1596:   extern PetscErrorCode VecRestoreArray(Vec, double **);
1597:   extern PetscErrorCode VecGetArray(Vec, float **);
1598:   extern PetscErrorCode VecRestoreArray(Vec, float **);
1599:   extern PetscErrorCode VecGetArrayRead(Vec, const double **);
1600:   extern PetscErrorCode VecRestoreArrayRead(Vec, const double **);
1601:   extern PetscErrorCode VecGetArrayRead(Vec, const float **);
1602:   extern PetscErrorCode VecRestoreArrayRead(Vec, const float **);
1603:   if ((((PetscObject)x)->precision == PETSC_PRECISION_SINGLE) && (((PetscObject)y)->precision == PETSC_PRECISION_DOUBLE)) {
1604:     PetscInt     i, n;
1605:     const float *xx;
1606:     double      *yy;
1607:     VecGetArrayRead(x, &xx);
1608:     VecGetArray(y, &yy);
1609:     VecGetLocalSize(x, &n);
1610:     for (i = 0; i < n; i++) yy[i] = xx[i];
1611:     VecRestoreArrayRead(x, &xx);
1612:     VecRestoreArray(y, &yy);
1613:   } else if ((((PetscObject)x)->precision == PETSC_PRECISION_DOUBLE) && (((PetscObject)y)->precision == PETSC_PRECISION_SINGLE)) {
1614:     PetscInt      i, n;
1615:     float        *yy;
1616:     const double *xx;
1617:     VecGetArrayRead(x, &xx);
1618:     VecGetArray(y, &yy);
1619:     VecGetLocalSize(x, &n);
1620:     for (i = 0; i < n; i++) yy[i] = (float)xx[i];
1621:     VecRestoreArrayRead(x, &xx);
1622:     VecRestoreArray(y, &yy);
1623:   } else PetscUseTypeMethod(x, copy, y);
1624: #else
1625:   PetscUseTypeMethod(x, copy, y);
1626: #endif

1628:   PetscObjectStateIncrease((PetscObject)y);
1629: #if !defined(PETSC_USE_MIXED_PRECISION)
1630:   for (PetscInt i = 0; i < 4; i++) {
1631:     if (flgs[i]) PetscObjectComposedDataSetReal((PetscObject)y, NormIds[i], norms[i]);
1632:   }
1633: #endif

1635:   PetscLogEventEnd(VEC_Copy, x, y, 0, 0);
1636:   return 0;
1637: }

1639: /*@
1640:    VecSwap - Swaps the vectors `x` and `y`.

1642:    Logically Collective

1644:    Input Parameters:
1645: .  x, y  - the vectors

1647:    Level: advanced

1649: .seealso: [](chapter_vectors), `Vec`, `VecSet()`
1650: @*/
1651: PetscErrorCode VecSwap(Vec x, Vec y)
1652: {
1653:   PetscReal normxs[4], normys[4];
1654:   PetscBool flgxs[4], flgys[4];

1661:   VecCheckSameSize(x, 1, y, 2);
1664:   VecSetErrorIfLocked(x, 1);
1665:   VecSetErrorIfLocked(y, 2);

1667:   for (PetscInt i = 0; i < 4; i++) {
1668:     PetscObjectComposedDataGetReal((PetscObject)x, NormIds[i], normxs[i], flgxs[i]);
1669:     PetscObjectComposedDataGetReal((PetscObject)y, NormIds[i], normys[i], flgys[i]);
1670:   }

1672:   PetscLogEventBegin(VEC_Swap, x, y, 0, 0);
1673:   PetscUseTypeMethod(x, swap, y);
1674:   PetscLogEventEnd(VEC_Swap, x, y, 0, 0);

1676:   PetscObjectStateIncrease((PetscObject)x);
1677:   PetscObjectStateIncrease((PetscObject)y);
1678:   for (PetscInt i = 0; i < 4; i++) {
1679:     if (flgxs[i]) PetscObjectComposedDataSetReal((PetscObject)y, NormIds[i], normxs[i]);
1680:     if (flgys[i]) PetscObjectComposedDataSetReal((PetscObject)x, NormIds[i], normys[i]);
1681:   }
1682:   return 0;
1683: }

1685: /*@C
1686:   VecStashViewFromOptions - Processes command line options to determine if/how a `VecStash` object is to be viewed.

1688:   Collective

1690:   Input Parameters:
1691: + obj   - the `VecStash` object
1692: . bobj - optional other object that provides the prefix
1693: - optionname - option to activate viewing

1695:   Level: intermediate

1697:   Developer Note:
1698:   This cannot use `PetscObjectViewFromOptions()` because it takes a `Vec` as an argument but does not use VecView

1700: .seealso: [](chapter_vectors), `Vec`, `VecStashSetInitialSize()`
1701: @*/
1702: PetscErrorCode VecStashViewFromOptions(Vec obj, PetscObject bobj, const char optionname[])
1703: {
1704:   PetscViewer       viewer;
1705:   PetscBool         flg;
1706:   PetscViewerFormat format;
1707:   char             *prefix;

1709:   prefix = bobj ? bobj->prefix : ((PetscObject)obj)->prefix;
1710:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj), ((PetscObject)obj)->options, prefix, optionname, &viewer, &format, &flg);
1711:   if (flg) {
1712:     PetscViewerPushFormat(viewer, format);
1713:     VecStashView(obj, viewer);
1714:     PetscViewerPopFormat(viewer);
1715:     PetscViewerDestroy(&viewer);
1716:   }
1717:   return 0;
1718: }

1720: /*@
1721:    VecStashView - Prints the entries in the vector stash and block stash.

1723:    Collective

1725:    Input Parameters:
1726: +  v - the vector
1727: -  viewer - the viewer

1729:    Level: advanced

1731: .seealso: [](chapter_vectors), `Vec`, `VecSetBlockSize()`, `VecSetValues()`, `VecSetValuesBlocked()`
1732: @*/
1733: PetscErrorCode VecStashView(Vec v, PetscViewer viewer)
1734: {
1735:   PetscMPIInt rank;
1736:   PetscInt    i, j;
1737:   PetscBool   match;
1738:   VecStash   *s;
1739:   PetscScalar val;


1745:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &match);
1747:   PetscViewerASCIIUseTabs(viewer, PETSC_FALSE);
1748:   MPI_Comm_rank(PetscObjectComm((PetscObject)v), &rank);
1749:   s = &v->bstash;

1751:   /* print block stash */
1752:   PetscViewerASCIIPushSynchronized(viewer);
1753:   PetscViewerASCIISynchronizedPrintf(viewer, "[%d]Vector Block stash size %" PetscInt_FMT " block size %" PetscInt_FMT "\n", rank, s->n, s->bs);
1754:   for (i = 0; i < s->n; i++) {
1755:     PetscViewerASCIISynchronizedPrintf(viewer, "[%d] Element %" PetscInt_FMT " ", rank, s->idx[i]);
1756:     for (j = 0; j < s->bs; j++) {
1757:       val = s->array[i * s->bs + j];
1758: #if defined(PETSC_USE_COMPLEX)
1759:       PetscViewerASCIISynchronizedPrintf(viewer, "(%18.16e %18.16e) ", (double)PetscRealPart(val), (double)PetscImaginaryPart(val));
1760: #else
1761:       PetscViewerASCIISynchronizedPrintf(viewer, "%18.16e ", (double)val);
1762: #endif
1763:     }
1764:     PetscViewerASCIISynchronizedPrintf(viewer, "\n");
1765:   }
1766:   PetscViewerFlush(viewer);

1768:   s = &v->stash;

1770:   /* print basic stash */
1771:   PetscViewerASCIISynchronizedPrintf(viewer, "[%d]Vector stash size %" PetscInt_FMT "\n", rank, s->n);
1772:   for (i = 0; i < s->n; i++) {
1773:     val = s->array[i];
1774: #if defined(PETSC_USE_COMPLEX)
1775:     PetscViewerASCIISynchronizedPrintf(viewer, "[%d] Element %" PetscInt_FMT " (%18.16e %18.16e) ", rank, s->idx[i], (double)PetscRealPart(val), (double)PetscImaginaryPart(val));
1776: #else
1777:     PetscViewerASCIISynchronizedPrintf(viewer, "[%d] Element %" PetscInt_FMT " %18.16e\n", rank, s->idx[i], (double)val);
1778: #endif
1779:   }
1780:   PetscViewerFlush(viewer);
1781:   PetscViewerASCIIPopSynchronized(viewer);
1782:   PetscViewerASCIIUseTabs(viewer, PETSC_TRUE);
1783:   return 0;
1784: }

1786: PetscErrorCode PetscOptionsGetVec(PetscOptions options, const char prefix[], const char key[], Vec v, PetscBool *set)
1787: {
1788:   PetscInt     i, N, rstart, rend;
1789:   PetscScalar *xx;
1790:   PetscReal   *xreal;
1791:   PetscBool    iset;

1793:   VecGetOwnershipRange(v, &rstart, &rend);
1794:   VecGetSize(v, &N);
1795:   PetscCalloc1(N, &xreal);
1796:   PetscOptionsGetRealArray(options, prefix, key, xreal, &N, &iset);
1797:   if (iset) {
1798:     VecGetArray(v, &xx);
1799:     for (i = rstart; i < rend; i++) xx[i - rstart] = xreal[i];
1800:     VecRestoreArray(v, &xx);
1801:   }
1802:   PetscFree(xreal);
1803:   if (set) *set = iset;
1804:   return 0;
1805: }

1807: /*@
1808:    VecGetLayout - get `PetscLayout` describing vector layout

1810:    Not Collective

1812:    Input Parameter:
1813: .  x - the vector

1815:    Output Parameter:
1816: .  map - the layout

1818:    Level: developer

1820: .seealso: [](chapter_vectors), `Vec`, `VecGetSizes()`, `VecGetOwnershipRange()`, `VecGetOwnershipRanges()`
1821: @*/
1822: PetscErrorCode VecGetLayout(Vec x, PetscLayout *map)
1823: {
1826:   *map = x->map;
1827:   return 0;
1828: }

1830: /*@
1831:    VecSetLayout - set `PetscLayout` describing vector layout

1833:    Not Collective

1835:    Input Parameters:
1836: +  x - the vector
1837: -  map - the layout

1839:    Level: developer

1841:    Note:
1842:    It is normally only valid to replace the layout with a layout known to be equivalent.

1844: .seealso: [](chapter_vectors), `Vec`, `PetscLayout`, `VecGetLayout()`, `VecGetSizes()`, `VecGetOwnershipRange()`, `VecGetOwnershipRanges()`
1845: @*/
1846: PetscErrorCode VecSetLayout(Vec x, PetscLayout map)
1847: {
1849:   PetscLayoutReference(map, &x->map);
1850:   return 0;
1851: }

1853: PetscErrorCode VecSetInf(Vec xin)
1854: {
1855:   PetscInt     i, n = xin->map->n;
1856:   PetscScalar *xx;
1857:   PetscScalar  zero = 0.0, one = 1.0, inf = one / zero;

1859:   if (xin->ops->set) PetscUseTypeMethod(xin, set, inf);
1860:   else {
1861:     VecGetArrayWrite(xin, &xx);
1862:     for (i = 0; i < n; i++) xx[i] = inf;
1863:     VecRestoreArrayWrite(xin, &xx);
1864:   }
1865:   return 0;
1866: }

1868: /*@
1869:      VecBindToCPU - marks a vector to temporarily stay on the CPU and perform computations on the CPU

1871:   Logically collective

1873:    Input Parameters:
1874: +   v - the vector
1875: -   flg - bind to the CPU if value of `PETSC_TRUE`

1877:    Level: intermediate

1879: .seelaso: `VecBoundToCPU()`
1880: @*/
1881: PetscErrorCode VecBindToCPU(Vec v, PetscBool flg)
1882: {
1885: #if defined(PETSC_HAVE_DEVICE)
1886:   if (v->boundtocpu == flg) return 0;
1887:   v->boundtocpu = flg;
1888:   PetscTryTypeMethod(v, bindtocpu, flg);
1889: #endif
1890:   return 0;
1891: }

1893: /*@
1894:      VecBoundToCPU - query if a vector is bound to the CPU

1896:   Not collective

1898:    Input Parameter:
1899: .   v - the vector

1901:    Output Parameter:
1902: .   flg - the logical flag

1904:    Level: intermediate

1906: .seealso: [](chapter_vectors), `Vec`, `VecBindToCPU()`
1907: @*/
1908: PetscErrorCode VecBoundToCPU(Vec v, PetscBool *flg)
1909: {
1912: #if defined(PETSC_HAVE_DEVICE)
1913:   *flg = v->boundtocpu;
1914: #else
1915:   *flg = PETSC_TRUE;
1916: #endif
1917:   return 0;
1918: }

1920: /*@
1921:    VecSetBindingPropagates - Sets whether the state of being bound to the CPU for a GPU vector type propagates to child and some other associated objects

1923:    Input Parameters:
1924: +  v - the vector
1925: -  flg - flag indicating whether the boundtocpu flag should be propagated

1927:    Level: developer

1929:    Notes:
1930:    If the value of flg is set to true, then `VecDuplicate()` and `VecDuplicateVecs()` will bind created vectors to GPU if the input vector is bound to the CPU.
1931:    The created vectors will also have their bindingpropagates flag set to true.

1933:    Developer Note:
1934:    If a `DMDA` has the `-dm_bind_below option` set to true, then vectors created by `DMCreateGlobalVector()` will have `VecSetBindingPropagates()` called on them to
1935:    set their bindingpropagates flag to true.

1937: .seealso: [](chapter_vectors), `Vec`, `MatSetBindingPropagates()`, `VecGetBindingPropagates()`
1938: @*/
1939: PetscErrorCode VecSetBindingPropagates(Vec v, PetscBool flg)
1940: {
1942: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_CUDA)
1943:   v->bindingpropagates = flg;
1944: #endif
1945:   return 0;
1946: }

1948: /*@
1949:    VecGetBindingPropagates - Gets whether the state of being bound to the CPU for a GPU vector type propagates to child and some other associated objects

1951:    Input Parameter:
1952: .  v - the vector

1954:    Output Parameter:
1955: .  flg - flag indicating whether the boundtocpu flag will be propagated

1957:    Level: developer

1959: .seealso: [](chapter_vectors), `Vec`, `VecSetBindingPropagates()`
1960: @*/
1961: PetscErrorCode VecGetBindingPropagates(Vec v, PetscBool *flg)
1962: {
1965: #if defined(PETSC_HAVE_VIENNACL) || defined(PETSC_HAVE_CUDA)
1966:   *flg = v->bindingpropagates;
1967: #else
1968:   *flg = PETSC_FALSE;
1969: #endif
1970:   return 0;
1971: }

1973: /*@C
1974:   VecSetPinnedMemoryMin - Set the minimum data size for which pinned memory will be used for host (CPU) allocations.

1976:   Logically Collective

1978:   Input Parameters:
1979: +  v    - the vector
1980: -  mbytes - minimum data size in bytes

1982:   Options Database Key:
1983: . -vec_pinned_memory_min <size> - minimum size (in bytes) for an allocation to use pinned memory on host.
1984:                                   Note that this takes a PetscScalar, to accommodate large values;
1985:                                   specifying -1 ensures that pinned memory will never be used.

1987:   Level: developer

1989: .seealso: [](chapter_vectors), `Vec`, `VecGetPinnedMemoryMin()`
1990: @*/
1991: PetscErrorCode VecSetPinnedMemoryMin(Vec v, size_t mbytes)
1992: {
1994: #if PetscDefined(HAVE_DEVICE)
1995:   v->minimum_bytes_pinned_memory = mbytes;
1996: #endif
1997:   return 0;
1998: }

2000: /*@C
2001:   VecGetPinnedMemoryMin - Get the minimum data size for which pinned memory will be used for host (CPU) allocations.

2003:   Logically Collective

2005:   Input Parameters:
2006: .  v    - the vector

2008:   Output Parameters:
2009: .  mbytes - minimum data size in bytes

2011:   Level: developer

2013: .seealso: [](chapter_vectors), `Vec`, `VecSetPinnedMemoryMin()`
2014: @*/
2015: PetscErrorCode VecGetPinnedMemoryMin(Vec v, size_t *mbytes)
2016: {
2019: #if PetscDefined(HAVE_DEVICE)
2020:   *mbytes = v->minimum_bytes_pinned_memory;
2021: #endif
2022:   return 0;
2023: }

2025: /*@
2026:   VecGetOffloadMask - Get the offload mask of a `Vec`

2028:   Not Collective

2030:   Input Parameters:
2031: .   v - the vector

2033:   Output Parameters:
2034: .   mask - corresponding `PetscOffloadMask` enum value.

2036:    Level: intermediate

2038: .seealso: [](chapter_vectors), `Vec`, `VecCreateSeqCUDA()`, `VecCreateSeqViennaCL()`, `VecGetArray()`, `VecGetType()`
2039: @*/
2040: PetscErrorCode VecGetOffloadMask(Vec v, PetscOffloadMask *mask)
2041: {
2044:   *mask = v->offloadmask;
2045:   return 0;
2046: }

2048: #if !defined(PETSC_HAVE_VIENNACL)
2049: PETSC_EXTERN PetscErrorCode VecViennaCLGetCLContext(Vec v, PETSC_UINTPTR_T *ctx)
2050: {
2051:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to get a Vec's cl_context");
2052: }

2054: PETSC_EXTERN PetscErrorCode VecViennaCLGetCLQueue(Vec v, PETSC_UINTPTR_T *queue)
2055: {
2056:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to get a Vec's cl_command_queue");
2057: }

2059: PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMem(Vec v, PETSC_UINTPTR_T *queue)
2060: {
2061:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to get a Vec's cl_mem");
2062: }

2064: PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMemRead(Vec v, PETSC_UINTPTR_T *queue)
2065: {
2066:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to get a Vec's cl_mem");
2067: }

2069: PETSC_EXTERN PetscErrorCode VecViennaCLGetCLMemWrite(Vec v, PETSC_UINTPTR_T *queue)
2070: {
2071:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to get a Vec's cl_mem");
2072: }

2074: PETSC_EXTERN PetscErrorCode VecViennaCLRestoreCLMemWrite(Vec v)
2075: {
2076:   SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "PETSc must be configured with --with-opencl to restore a Vec's cl_mem");
2077: }
2078: #endif