Actual source code: vector.c

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

  8: /* Logging support */
  9: PetscClassId  VEC_CLASSID;
 10: PetscLogEvent  VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, 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_NormBarrier, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin, VEC_ScatterBegin, VEC_ScatterEnd;
 13: PetscLogEvent  VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier;
 14: PetscLogEvent  VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication,VEC_Ops;
 15: PetscLogEvent  VEC_DotNormBarrier, VEC_DotNorm, VEC_AXPBYPCZ, VEC_CUSPCopyFromGPU, VEC_CUSPCopyToGPU;
 16: PetscLogEvent  VEC_CUSPCopyFromGPUSome, VEC_CUSPCopyToGPUSome;

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

 25:     Not collective

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

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

 36:    Level: advanced

 38: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()

 40: @*/
 41: PetscErrorCode  VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
 42: {
 45:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
 46:   VecStashGetInfo_Private(&vec->bstash,bnstash,breallocs);
 47:   return(0);
 48: }

 52: /*@
 53:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
 54:    by the routine VecSetValuesLocal() to allow users to insert vector entries
 55:    using a local (per-processor) numbering.

 57:    Logically Collective on Vec

 59:    Input Parameters:
 60: +  x - vector
 61: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

 63:    Notes:
 64:    All vectors obtained with VecDuplicate() from this vector inherit the same mapping.

 66:    Level: intermediate

 68:    Concepts: vector^setting values with local numbering

 70: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
 71:            VecSetLocalToGlobalMappingBlock(), VecSetValuesBlockedLocal()
 72: @*/
 73: PetscErrorCode  VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
 74: {


 81:   if (x->ops->setlocaltoglobalmapping) {
 82:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
 83:   } else {
 84:     PetscLayoutSetISLocalToGlobalMapping(x->map,mapping);
 85:   }
 86:   return(0);
 87: }

 91: /*@
 92:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
 93:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
 94:    using a local (per-processor) numbering.

 96:    Logically Collective on Vec

 98:    Input Parameters:
 99: +  x - vector
100: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

102:    Notes:
103:    All vectors obtained with VecDuplicate() from this vector inherit the same mapping.

105:    Level: intermediate

107:    Concepts: vector^setting values blocked with local numbering

109: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
110:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
111: @*/
112: PetscErrorCode  VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
113: {


120:   PetscLayoutSetISLocalToGlobalMappingBlock(x->map,mapping);
121:   return(0);
122: }

126: /*@
127:    VecGetLocalToGlobalMapping - Gets the local-to-global numbering set by VecSetLocalToGlobalMapping()

129:    Not Collective

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

134:    Output Parameter:
135: .  mapping - the mapping

137:    Level: advanced

139:    Concepts: vectors^local to global mapping
140:    Concepts: local to global mapping^for vectors

142: .seealso:  VecSetValuesLocal(), VecGetLocalToGlobalMappingBlock()
143: @*/
144: PetscErrorCode VecGetLocalToGlobalMapping(Vec X,ISLocalToGlobalMapping *mapping)
145: {
150:   *mapping = X->map->mapping;
151:   return(0);
152: }

156: /*@
157:    VecGetLocalToGlobalMappingBlock - Gets the local-to-global numbering set by VecSetLocalToGlobalMappingBlock()

159:    Not Collective

161:    Input Parameters:
162: .  X - the vector

164:    Output Parameters:
165: .  mapping - the mapping

167:    Level: advanced

169:    Concepts: vectors^local to global mapping blocked
170:    Concepts: local to global mapping^for vectors, blocked

172: .seealso:  VecSetValuesBlockedLocal(), VecGetLocalToGlobalMapping()
173: @*/
174: PetscErrorCode VecGetLocalToGlobalMappingBlock(Vec X,ISLocalToGlobalMapping *mapping)
175: {
180:   *mapping = X->map->bmapping;
181:   return(0);
182: }

186: /*@
187:    VecAssemblyBegin - Begins assembling the vector.  This routine should
188:    be called after completing all calls to VecSetValues().

190:    Collective on Vec

192:    Input Parameter:
193: .  vec - the vector

195:    Level: beginner

197:    Concepts: assembly^vectors

199: .seealso: VecAssemblyEnd(), VecSetValues()
200: @*/
201: PetscErrorCode  VecAssemblyBegin(Vec vec)
202: {
204:   PetscBool      flg = PETSC_FALSE;


210:   PetscOptionsGetBool(((PetscObject)vec)->prefix,"-vec_view_stash",&flg,PETSC_NULL);
211:   if (flg) {
212:     PetscViewer viewer;
213:     PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
214:     VecStashView(vec,viewer);
215:   }

217:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
218:   if (vec->ops->assemblybegin) {
219:     (*vec->ops->assemblybegin)(vec);
220:   }
221:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
222:   PetscObjectStateIncrease((PetscObject)vec);
223:   return(0);
224: }

228: /*
229:   Processes command line options to determine if/how a matrix
230:   is to be viewed. Called by VecAssemblyEnd().

232: .seealso: MatView_Private()

234: */
235: PetscErrorCode  VecView_Private(Vec vec)
236: {
238:   PetscBool      flg = PETSC_FALSE;

241:   PetscObjectOptionsBegin((PetscObject)vec);
242:     PetscOptionsBool("-vec_view","Print vector to stdout","VecView",flg,&flg,PETSC_NULL);
243:     if (flg) {
244:       PetscViewer viewer;
245:       PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
246:       VecView(vec,viewer);
247:     }
248:     flg  = PETSC_FALSE;
249:     PetscOptionsBool("-vec_view_matlab","Print vector to stdout in a format MATLAB can read","VecView",flg,&flg,PETSC_NULL);
250:     if (flg) {
251:       PetscViewer viewer;
252:       PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
253:       PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);
254:       VecView(vec,viewer);
255:       PetscViewerPopFormat(viewer);
256:     }
257: #if defined(PETSC_HAVE_MATLAB_ENGINE)
258:     flg  = PETSC_FALSE;
259:     PetscOptionsBool("-vec_view_matlab_file","Print vector to matlaboutput.mat format MATLAB can read","VecView",flg,&flg,PETSC_NULL);
260:     if (flg) {
261:       VecView(vec,PETSC_VIEWER_MATLAB_(((PetscObject)vec)->comm));
262:     }
263: #endif
264: #if defined(PETSC_USE_SOCKET_VIEWER)
265:     flg  = PETSC_FALSE;
266:     PetscOptionsBool("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",flg,&flg,PETSC_NULL);
267:     if (flg) {
268:       VecView(vec,PETSC_VIEWER_SOCKET_(((PetscObject)vec)->comm));
269:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(((PetscObject)vec)->comm));
270:     }
271: #endif
272:     flg  = PETSC_FALSE;
273:     PetscOptionsBool("-vec_view_binary","Save vector to file in binary format","VecView",flg,&flg,PETSC_NULL);
274:     if (flg) {
275:       VecView(vec,PETSC_VIEWER_BINARY_(((PetscObject)vec)->comm));
276:       PetscViewerFlush(PETSC_VIEWER_BINARY_(((PetscObject)vec)->comm));
277:     }
278:   PetscOptionsEnd();
279:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
280:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
281:   flg  = PETSC_FALSE;
282:   PetscOptionsGetBool(((PetscObject)vec)->prefix,"-vec_view_draw",&flg,PETSC_NULL);
283:   if (flg) {
284:     VecView(vec,PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
285:     PetscViewerFlush(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
286:   }
287:   flg  = PETSC_FALSE;
288:   PetscOptionsGetBool(((PetscObject)vec)->prefix,"-vec_view_draw_lg",&flg,PETSC_NULL);
289:   if (flg) {
290:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm),PETSC_VIEWER_DRAW_LG);
291:     VecView(vec,PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
292:     PetscViewerFlush(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
293:   }
294:   return(0);
295: }

299: /*@
300:    VecAssemblyEnd - Completes assembling the vector.  This routine should
301:    be called after VecAssemblyBegin().

303:    Collective on Vec

305:    Input Parameter:
306: .  vec - the vector

308:    Options Database Keys:
309: +  -vec_view - Prints vector in ASCII format
310: .  -vec_view_matlab - Prints vector in ASCII MATLAB format to stdout
311: .  -vec_view_matlab_file - Prints vector in MATLAB format to matlaboutput.mat
312: .  -vec_view_draw - Activates vector viewing using drawing tools
313: .  -display <name> - Sets display name (default is host)
314: .  -draw_pause <sec> - Sets number of seconds to pause after display
315: -  -vec_view_socket - Activates vector viewing using a socket

317:    Level: beginner

319: .seealso: VecAssemblyBegin(), VecSetValues()
320: @*/
321: PetscErrorCode  VecAssemblyEnd(Vec vec)
322: {

327:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
329:   if (vec->ops->assemblyend) {
330:     (*vec->ops->assemblyend)(vec);
331:   }
332:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
333:   VecView_Private(vec);
334:   return(0);
335: }

339: /*@
340:    VecPointwiseMax - Computes the componentwise maximum w_i = max(x_i, y_i).

342:    Logically Collective on Vec

344:    Input Parameters:
345: .  x, y  - the vectors

347:    Output Parameter:
348: .  w - the result

350:    Level: advanced

352:    Notes: any subset of the x, y, and w may be the same vector.
353:           For complex numbers compares only the real part

355:    Concepts: vector^pointwise multiply

357: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
358: @*/
359: PetscErrorCode  VecPointwiseMax(Vec w,Vec x,Vec y)
360: {

372:   if (x->map->N != y->map->N || x->map->N != w->map->N) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
373:   if (x->map->n != y->map->n || x->map->n != w->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

375:   (*w->ops->pointwisemax)(w,x,y);
376:   PetscObjectStateIncrease((PetscObject)w);
377:   return(0);
378: }


383: /*@
384:    VecPointwiseMin - Computes the componentwise minimum w_i = min(x_i, y_i).

386:    Logically Collective on Vec

388:    Input Parameters:
389: .  x, y  - the vectors

391:    Output Parameter:
392: .  w - the result

394:    Level: advanced

396:    Notes: any subset of the x, y, and w may be the same vector.
397:           For complex numbers compares only the real part

399:    Concepts: vector^pointwise multiply

401: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
402: @*/
403: PetscErrorCode  VecPointwiseMin(Vec w,Vec x,Vec y)
404: {

416:   if (x->map->N != y->map->N || x->map->N != w->map->N) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
417:   if (x->map->n != y->map->n || x->map->n != w->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

419:   (*w->ops->pointwisemin)(w,x,y);
420:   PetscObjectStateIncrease((PetscObject)w);
421:   return(0);
422: }

426: /*@
427:    VecPointwiseMaxAbs - Computes the componentwise maximum of the absolute values w_i = max(abs(x_i), abs(y_i)).

429:    Logically Collective on Vec

431:    Input Parameters:
432: .  x, y  - the vectors

434:    Output Parameter:
435: .  w - the result

437:    Level: advanced

439:    Notes: any subset of the x, y, and w may be the same vector.

441:    Concepts: vector^pointwise multiply

443: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
444: @*/
445: PetscErrorCode  VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
446: {

458:   if (x->map->N != y->map->N || x->map->N != w->map->N) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
459:   if (x->map->n != y->map->n || x->map->n != w->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

461:   (*w->ops->pointwisemaxabs)(w,x,y);
462:   PetscObjectStateIncrease((PetscObject)w);
463:   return(0);
464: }

468: /*@
469:    VecPointwiseDivide - Computes the componentwise division w = x/y.

471:    Logically Collective on Vec

473:    Input Parameters:
474: .  x, y  - the vectors

476:    Output Parameter:
477: .  w - the result

479:    Level: advanced

481:    Notes: any subset of the x, y, and w may be the same vector.

483:    Concepts: vector^pointwise divide

485: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
486: @*/
487: PetscErrorCode  VecPointwiseDivide(Vec w,Vec x,Vec y)
488: {

500:   if (x->map->N != y->map->N || x->map->N != w->map->N) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
501:   if (x->map->n != y->map->n || x->map->n != w->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

503:   (*w->ops->pointwisedivide)(w,x,y);
504:   PetscObjectStateIncrease((PetscObject)w);
505:   return(0);
506: }


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

514:    Collective on Vec

516:    Input Parameters:
517: .  v - a vector to mimic

519:    Output Parameter:
520: .  newv - location to put new vector

522:    Notes:
523:    VecDuplicate() does not copy the vector, but rather allocates storage
524:    for the new vector.  Use VecCopy() to copy a vector.

526:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
527:    vectors.

529:    Level: beginner

531: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
532: @*/
533: PetscErrorCode  VecDuplicate(Vec v,Vec *newv)
534: {

541:   (*v->ops->duplicate)(v,newv);
542:   PetscObjectStateIncrease((PetscObject)*newv);
543:   return(0);
544: }

548: /*@
549:    VecDestroy - Destroys a vector.

551:    Collective on Vec

553:    Input Parameters:
554: .  v  - the vector

556:    Level: beginner

558: .seealso: VecDuplicate(), VecDestroyVecs()
559: @*/
560: PetscErrorCode  VecDestroy(Vec *v)
561: {

565:   if (!*v) return(0);
567:   if (--((PetscObject)(*v))->refct > 0) {*v = 0; return(0);}
568:   /* destroy the internal part */
569:   if ((*v)->ops->destroy) {
570:     (*(*v)->ops->destroy)(*v);
571:   }
572:   /* destroy the external/common part */
573:   PetscLayoutDestroy(&(*v)->map);
574:   PetscHeaderDestroy(v);
575:   return(0);
576: }

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

583:    Collective on Vec

585:    Input Parameters:
586: +  m - the number of vectors to obtain
587: -  v - a vector to mimic

589:    Output Parameter:
590: .  V - location to put pointer to array of vectors

592:    Notes:
593:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
594:    vector.

596:    Fortran Note:
597:    The Fortran interface is slightly different from that given below, it
598:    requires one to pass in V a Vec (integer) array of size at least m.
599:    See the Fortran chapter of the users manual and petsc/src/vec/vec/examples for details.

601:    Level: intermediate

603: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
604: @*/
605: PetscErrorCode  VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
606: {

613:   (*v->ops->duplicatevecs)(v, m,V);
614:   return(0);
615: }

619: /*@C
620:    VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().

622:    Collective on Vec

624:    Input Parameters:
625: +  vv - pointer to pointer to array of vector pointers
626: -  m - the number of vectors previously obtained

628:    Fortran Note:
629:    The Fortran interface is slightly different from that given below.
630:    See the Fortran chapter of the users manual

632:    Level: intermediate

634: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
635: @*/
636: PetscErrorCode  VecDestroyVecs(PetscInt m,Vec *vv[])
637: {

642:   if (!*vv) return(0);
645:   if (m < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of vectors %D",m);
646:   (*(**vv)->ops->destroyvecs)(m,*vv);
647:   *vv = 0;
648:   return(0);
649: }

651: #undef  __FUNCT__
653: /*@
654:   VecViewFromOptions - This function visualizes the vector based upon user options.

656:   Collective on Vec

658:   Input Parameters:
659: . vec   - The vector
660: . title - The title (currently ignored)

662:   Level: intermediate

664: .keywords: Vec, view, options, database
665: .seealso: VecSetFromOptions(), VecView()
666: @*/
667: PetscErrorCode  VecViewFromOptions(Vec vec, const char *title)
668: {

672:   VecView_Private(vec);
673:   return(0);
674: }

678: /*@C
679:    VecView - Views a vector object.

681:    Collective on Vec

683:    Input Parameters:
684: +  vec - the vector
685: -  viewer - an optional visualization context

687:    Notes:
688:    The available visualization contexts include
689: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
690: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
691:          output where only the first processor opens
692:          the file.  All other processors send their
693:          data to the first processor to print.

695:    You can change the format the vector is printed using the
696:    option PetscViewerSetFormat().

698:    The user can open alternative visualization contexts with
699: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
700: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
701:          specified file; corresponding input uses VecLoad()
702: .    PetscViewerDrawOpen() - Outputs vector to an X window display
703: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

705:    The user can call PetscViewerSetFormat() to specify the output
706:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
707:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
708: +    PETSC_VIEWER_DEFAULT - default, prints vector contents
709: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in MATLAB format
710: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
711: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
712:          format common among all vector types

714:    Notes for HDF5 Viewer: the name of the Vec (given with PetscObjectSetName() is the name that is used
715:    for the object in the HDF5 file. If you wish to store the same vector to the HDF5 viewer (with different values,
716:    obviously) several times, you must change its name each time before calling the VecView(). The name you use
717:    here should equal the name that you use in the Vec object that you use with VecLoad().

719:    See the manual page for VecLoad() on the exact format the binary viewer stores
720:    the values in the file.

722:    Level: beginner

724:    Concepts: vector^printing
725:    Concepts: vector^saving to disk

727: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
728:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
729:           PetscRealView(), PetscScalarView(), PetscIntView()
730: @*/
731: PetscErrorCode  VecView(Vec vec,PetscViewer viewer)
732: {
733:   PetscErrorCode    ierr;

738:   if (!viewer) {
739:     PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
740:   }
743:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

745:   PetscLogEventBegin(VEC_View,vec,viewer,0,0);
746:   (*vec->ops->view)(vec,viewer);
747:   PetscLogEventEnd(VEC_View,vec,viewer,0,0);
748:   return(0);
749: }

751: #if defined(PETSC_USE_DEBUG)
752: #include <../src/sys/totalview/tv_data_display.h>
753: PETSC_UNUSED static int TV_display_type(const struct _p_Vec *v)
754: {
755:   const PetscScalar *values;
756:   char              type[32];
757:   PetscErrorCode    ierr;


760:   TV_add_row("Local rows", "int", &v->map->n);
761:   TV_add_row("Global rows", "int", &v->map->N);
762:   TV_add_row("Typename", TV_ascii_string_type , ((PetscObject)v)->type_name);
763:   VecGetArrayRead((Vec)v,&values);
764:   PetscSNPrintf(type,32,"double[%d]",v->map->n);
765:   TV_add_row("values",type, values);
766:   VecRestoreArrayRead((Vec)v,&values);
767:   return TV_format_OK;
768: }
769: #endif

773: /*@
774:    VecGetSize - Returns the global number of elements of the vector.

776:    Not Collective

778:    Input Parameter:
779: .  x - the vector

781:    Output Parameters:
782: .  size - the global length of the vector

784:    Level: beginner

786:    Concepts: vector^local size

788: .seealso: VecGetLocalSize()
789: @*/
790: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
791: {

798:   (*x->ops->getsize)(x,size);
799:   return(0);
800: }

804: /*@
805:    VecGetLocalSize - Returns the number of elements of the vector stored
806:    in local memory. This routine may be implementation dependent, so use
807:    with care.

809:    Not Collective

811:    Input Parameter:
812: .  x - the vector

814:    Output Parameter:
815: .  size - the length of the local piece of the vector

817:    Level: beginner

819:    Concepts: vector^size

821: .seealso: VecGetSize()
822: @*/
823: PetscErrorCode  VecGetLocalSize(Vec x,PetscInt *size)
824: {

831:   (*x->ops->getlocalsize)(x,size);
832:   return(0);
833: }

837: /*@C
838:    VecGetOwnershipRange - Returns the range of indices owned by
839:    this processor, assuming that the vectors are laid out with the
840:    first n1 elements on the first processor, next n2 elements on the
841:    second, etc.  For certain parallel layouts this range may not be
842:    well defined.

844:    Not Collective

846:    Input Parameter:
847: .  x - the vector

849:    Output Parameters:
850: +  low - the first local element, pass in PETSC_NULL if not interested
851: -  high - one more than the last local element, pass in PETSC_NULL if not interested

853:    Note:
854:    The high argument is one more than the last element stored locally.

856:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

858:    Level: beginner

860:    Concepts: ownership^of vectors
861:    Concepts: vector^ownership of elements

863: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
864: @*/
865: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
866: {
872:   if (low)  *low  = x->map->rstart;
873:   if (high) *high = x->map->rend;
874:   return(0);
875: }

879: /*@C
880:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor,
881:    assuming that the vectors are laid out with the
882:    first n1 elements on the first processor, next n2 elements on the
883:    second, etc.  For certain parallel layouts this range may not be
884:    well defined.

886:    Not Collective

888:    Input Parameter:
889: .  x - the vector

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

894:    Note:
895:    The high argument is one more than the last element stored locally.

897:    Fortran: You must PASS in an array of length size+1

899:    Level: beginner

901:    Concepts: ownership^of vectors
902:    Concepts: vector^ownership of elements

904: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
905: @*/
906: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
907: {

913:   PetscLayoutGetRanges(x->map,ranges);
914:   return(0);
915: }

919: /*@
920:    VecSetOption - Sets an option for controling a vector's behavior.

922:    Collective on Vec

924:    Input Parameter:
925: +  x - the vector
926: .  op - the option
927: -  flag - turn the option on or off

929:    Supported Options:
930: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
931:           entries destined to be stored on a separate processor. This can be used
932:           to eliminate the global reduction in the VecAssemblyXXXX() if you know
933:           that you have only used VecSetValues() to set local elements
934: .     VEC_IGNORE_NEGATIVE_INDICES, which means you can pass negative indices
935:           in ix in calls to VecSetValues or VecGetValues. These rows are simply
936:           ignored.

938:    Level: intermediate

940: @*/
941: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscBool  flag)
942: {

948:   if (x->ops->setoption) {
949:     (*x->ops->setoption)(x,op,flag);
950:   }
951:   return(0);
952: }

956: /* Default routines for obtaining and releasing; */
957: /* may be used by any implementation */
958: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
959: {
961:   PetscInt       i;

966:   if (m <= 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
967:   PetscMalloc(m*sizeof(Vec*),V);
968:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
969:   return(0);
970: }

974: PetscErrorCode VecDestroyVecs_Default(PetscInt m,Vec v[])
975: {
977:   PetscInt       i;

981:   if (m <= 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
982:   for (i=0; i<m; i++) {VecDestroy(&v[i]);}
983:   PetscFree(v);
984:   return(0);
985: }

989: /*@
990:    VecResetArray - Resets a vector to use its default memory. Call this
991:    after the use of VecPlaceArray().

993:    Not Collective

995:    Input Parameters:
996: .  vec - the vector

998:    Level: developer

1000: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()

1002: @*/
1003: PetscErrorCode  VecResetArray(Vec vec)
1004: {

1010:   if (vec->ops->resetarray) {
1011:     (*vec->ops->resetarray)(vec);
1012:   } else SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Cannot reset array in this type of vector");
1013:   PetscObjectStateIncrease((PetscObject)vec);
1014:   return(0);
1015: }

1019: /*@C
1020:   VecLoad - Loads a vector that has been stored in binary or HDF5 format
1021:   with VecView().

1023:   Collective on PetscViewer 

1025:   Input Parameters:
1026: + newvec - the newly loaded vector, this needs to have been created with VecCreate() or
1027:            some related function before a call to VecLoad(). 
1028: - viewer - binary file viewer, obtained from PetscViewerBinaryOpen() or
1029:            HDF5 file viewer, obtained from PetscViewerHDF5Open()

1031:    Level: intermediate

1033:   Notes:
1034:   Defaults to the standard Seq or MPI Vec, if you want some other type of Vec call VecSetFromOptions()
1035:   before calling this.

1037:   The input file must contain the full global vector, as
1038:   written by the routine VecView().

1040:   If the type or size of newvec is not set before a call to VecLoad, PETSc 
1041:   sets the type and the local and global sizes.If type and/or 
1042:   sizes are already set, then the same are used.

1044:   IF using HDF5, you must assign the Vec the same name as was used in the Vec
1045:   that was stored in the file using PetscObjectSetName(). Otherwise you will
1046:   get the error message: "Cannot H5DOpen2() with Vec name NAMEOFOBJECT"

1048:   Notes for advanced users:
1049:   Most users should not need to know the details of the binary storage
1050:   format, since VecLoad() and VecView() completely hide these details.
1051:   But for anyone who's interested, the standard binary matrix storage
1052:   format is
1053: .vb
1054:      int    VEC_FILE_CLASSID
1055:      int    number of rows
1056:      PetscScalar *values of all entries
1057: .ve

1059:    In addition, PETSc automatically does the byte swapping for
1060: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
1061: linux, Windows and the paragon; thus if you write your own binary
1062: read/write routines you have to swap the bytes; see PetscBinaryRead()
1063: and PetscBinaryWrite() to see how this may be done.

1065:   Concepts: vector^loading from file

1067: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
1068: @*/
1069: PetscErrorCode  VecLoad(Vec newvec, PetscViewer viewer)
1070: {


1077:   PetscLogEventBegin(VEC_Load,viewer,0,0,0);
1078:   if (!((PetscObject)newvec)->type_name && !newvec->ops->create) {
1079:     VecSetType(newvec, VECSTANDARD);
1080:   }
1081:   (*newvec->ops->load)(newvec,viewer);
1082:   PetscLogEventEnd(VEC_Load,viewer,0,0,0);
1083:   return(0);
1084: }

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

1091:    Logically Collective on Vec

1093:    Input Parameter:
1094: .  vec - the vector

1096:    Output Parameter:
1097: .  vec - the vector reciprocal

1099:    Level: intermediate

1101:    Concepts: vector^reciprocal

1103: .seealso: VecLog(), VecExp(), VecSqrtAbs()

1105: @*/
1106: PetscErrorCode  VecReciprocal(Vec vec)
1107: {

1113:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1114:   if (!vec->ops->reciprocal) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Vector does not support reciprocal operation");
1115:   (*vec->ops->reciprocal)(vec);
1116:   PetscObjectStateIncrease((PetscObject)vec);
1117:   return(0);
1118: }

1122: PetscErrorCode  VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
1123: {
1126:   (((void(**)(void))vec->ops)[(int)op]) = f;
1127:   return(0);
1128: }


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

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

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

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

1149:    Level: intermediate

1151:    Notes:
1152:      The block-stash is used for values set with VecSetValuesBlocked() while
1153:      the stash is used for values set with VecSetValues()

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

1161:    Concepts: vector^stash
1162:    Concepts: stash^vector

1164: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()

1166: @*/
1167: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1168: {

1173:   VecStashSetInitialSize_Private(&vec->stash,size);
1174:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1175:   return(0);
1176: }

1180: /*@
1181:    VecConjugate - Conjugates a vector.

1183:    Logically Collective on Vec

1185:    Input Parameters:
1186: .  x - the vector

1188:    Level: intermediate

1190:    Concepts: vector^conjugate

1192: @*/
1193: PetscErrorCode  VecConjugate(Vec x)
1194: {
1195: #ifdef PETSC_USE_COMPLEX

1201:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1202:   (*x->ops->conjugate)(x);
1203:   /* we need to copy norms here */
1204:   PetscObjectStateIncrease((PetscObject)x);
1205:   return(0);
1206: #else
1207:   return(0);
1208: #endif
1209: }

1213: /*@
1214:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1216:    Logically Collective on Vec

1218:    Input Parameters:
1219: .  x, y  - the vectors

1221:    Output Parameter:
1222: .  w - the result

1224:    Level: advanced

1226:    Notes: any subset of the x, y, and w may be the same vector.

1228:    Concepts: vector^pointwise multiply

1230: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1231: @*/
1232: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
1233: {

1245:   if (x->map->n != y->map->n || x->map->n != w->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1247:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1248:   (*w->ops->pointwisemult)(w,x,y);
1249:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1250:   PetscObjectStateIncrease((PetscObject)w);
1251:   return(0);
1252: }

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

1259:    Logically Collective on Vec

1261:    Input Parameters:
1262: +  x  - the vector
1263: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1264:           it will create one internally.

1266:    Output Parameter:
1267: .  x  - the vector

1269:    Example of Usage:
1270: .vb
1271:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1272:      VecSetRandom(x,rctx);
1273:      PetscRandomDestroy(rctx);
1274: .ve

1276:    Level: intermediate

1278:    Concepts: vector^setting to random
1279:    Concepts: random^vector

1281: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1282: @*/
1283: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
1284: {
1286:   PetscRandom    randObj = PETSC_NULL;

1292:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");

1294:   if (!rctx) {
1295:     MPI_Comm    comm;
1296:     PetscObjectGetComm((PetscObject)x,&comm);
1297:     PetscRandomCreate(comm,&randObj);
1298:     PetscRandomSetFromOptions(randObj);
1299:     rctx = randObj;
1300:   }

1302:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1303:   (*x->ops->setrandom)(x,rctx);
1304:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);

1306:   PetscRandomDestroy(&randObj);
1307:   PetscObjectStateIncrease((PetscObject)x);
1308:   return(0);
1309: }

1313: /*@
1314:   VecZeroEntries - puts a 0.0 in each element of a vector

1316:   Logically Collective on Vec

1318:   Input Parameter:
1319: . vec - The vector

1321:   Level: beginner

1323:   Developer Note: This routine does not need to exist since the exact functionality is obtained with 
1324:      VecSet(vec,0);  I guess someone added it to mirror the functionality of MatZeroEntries() but Mat is nothing
1325:      like a Vec (one is an operator and one is an element of a vector space, yeah yeah dual blah blah blah) so 
1326:      this routine should not exist.

1328: .keywords: Vec, set, options, database
1329: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1330: @*/
1331: PetscErrorCode  VecZeroEntries(Vec vec)
1332: {
1335:   VecSet(vec,0);
1336:   return(0);
1337: }

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

1345:   Collective on Vec

1347:   Input Parameter:
1348: . vec - The vector

1350:   Level: intermediate

1352: .keywords: Vec, set, options, database, type
1353: .seealso: VecSetFromOptions(), VecSetType()
1354: */
1355: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
1356: {
1357:   PetscBool      opt;
1358:   const VecType  defaultType;
1359:   char           typeName[256];
1360:   PetscMPIInt    size;

1364:   if (((PetscObject)vec)->type_name) {
1365:     defaultType = ((PetscObject)vec)->type_name;
1366:   } else {
1367:     MPI_Comm_size(((PetscObject)vec)->comm, &size);
1368:     if (size > 1) {
1369:       defaultType = VECMPI;
1370:     } else {
1371:       defaultType = VECSEQ;
1372:     }
1373:   }

1375:   if (!VecRegisterAllCalled) {VecRegisterAll(PETSC_NULL);}
1376:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
1377:   if (opt) {
1378:     VecSetType(vec, typeName);
1379:   } else {
1380:     VecSetType(vec, defaultType);
1381:   }
1382:   return(0);
1383: }

1387: /*@
1388:   VecSetFromOptions - Configures the vector from the options database.

1390:   Collective on Vec

1392:   Input Parameter:
1393: . vec - The vector

1395:   Notes:  To see all options, run your program with the -help option, or consult the users manual.
1396:           Must be called after VecCreate() but before the vector is used.

1398:   Level: beginner

1400:   Concepts: vectors^setting options
1401:   Concepts: vectors^setting type

1403: .keywords: Vec, set, options, database
1404: .seealso: VecCreate(), VecSetOptionsPrefix()
1405: @*/
1406: PetscErrorCode  VecSetFromOptions(Vec vec)
1407: {


1413:   PetscObjectOptionsBegin((PetscObject)vec);
1414:     /* Handle vector type options */
1415:     VecSetTypeFromOptions_Private(vec);

1417:     /* Handle specific vector options */
1418:     if (vec->ops->setfromoptions) {
1419:       (*vec->ops->setfromoptions)(vec);
1420:     }

1422:     /* process any options handlers added with PetscObjectAddOptionsHandler() */
1423:     PetscObjectProcessOptionsHandlers((PetscObject)vec);
1424:   PetscOptionsEnd();

1426:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1427:   return(0);
1428: }

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

1435:   Collective on Vec

1437:   Input Parameters:
1438: + v - the vector
1439: . n - the local size (or PETSC_DECIDE to have it set)
1440: - N - the global size (or PETSC_DECIDE)

1442:   Notes:
1443:   n and N cannot be both PETSC_DECIDE
1444:   If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.

1446:   Level: intermediate

1448: .seealso: VecGetSize(), PetscSplitOwnership()
1449: @*/
1450: PetscErrorCode  VecSetSizes(Vec v, PetscInt n, PetscInt N)
1451: {

1456:   if (N > 0 && n > N) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
1457:   if ((v->map->n >= 0 || v->map->N >= 0) && (v->map->n != n || v->map->N != N)) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_SUP,"Cannot change/reset vector sizes to %D local %D global after previously setting them to %D local %D global",n,N,v->map->n,v->map->N);
1458:   v->map->n = n;
1459:   v->map->N = N;
1460:   if (v->ops->create) {
1461:     (*v->ops->create)(v);
1462:     v->ops->create = 0;
1463:   }
1464:   return(0);
1465: }

1469: /*@
1470:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
1471:    and VecSetValuesBlockedLocal().

1473:    Logically Collective on Vec

1475:    Input Parameter:
1476: +  v - the vector
1477: -  bs - the blocksize

1479:    Notes:
1480:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1482:    Level: advanced

1484: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlock(), VecGetBlockSize()

1486:   Concepts: block size^vectors
1487: @*/
1488: PetscErrorCode  VecSetBlockSize(Vec v,PetscInt bs)
1489: {
1492:   if (bs <= 0) bs = 1;
1493:   if (bs == v->map->bs) return(0);
1494:   if (v->map->N != -1 && v->map->N % bs) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %D %D",v->map->N,bs);
1495:   if (v->map->n != -1 && v->map->n % bs) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
1496:    Try setting blocksize before setting the vector type",v->map->n,bs);

1499:   v->map->bs   = bs;
1500:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
1501:   return(0);
1502: }

1506: /*@
1507:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
1508:    and VecSetValuesBlockedLocal().

1510:    Not Collective

1512:    Input Parameter:
1513: .  v - the vector

1515:    Output Parameter:
1516: .  bs - the blocksize

1518:    Notes:
1519:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1521:    Level: advanced

1523: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlock(), VecSetBlockSize()

1525:    Concepts: vector^block size
1526:    Concepts: block^vector

1528: @*/
1529: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1530: {
1534:   *bs = v->map->bs;
1535:   return(0);
1536: }

1540: /*@C
1541:    VecSetOptionsPrefix - Sets the prefix used for searching for all
1542:    Vec options in the database.

1544:    Logically Collective on Vec

1546:    Input Parameter:
1547: +  v - the Vec context
1548: -  prefix - the prefix to prepend to all option names

1550:    Notes:
1551:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1552:    The first character of all runtime options is AUTOMATICALLY the hyphen.

1554:    Level: advanced

1556: .keywords: Vec, set, options, prefix, database

1558: .seealso: VecSetFromOptions()
1559: @*/
1560: PetscErrorCode  VecSetOptionsPrefix(Vec v,const char prefix[])
1561: {

1566:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1567:   return(0);
1568: }

1572: /*@C
1573:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all
1574:    Vec options in the database.

1576:    Logically Collective on Vec

1578:    Input Parameters:
1579: +  v - the Vec context
1580: -  prefix - the prefix to prepend to all option names

1582:    Notes:
1583:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1584:    The first character of all runtime options is AUTOMATICALLY the hyphen.

1586:    Level: advanced

1588: .keywords: Vec, append, options, prefix, database

1590: .seealso: VecGetOptionsPrefix()
1591: @*/
1592: PetscErrorCode  VecAppendOptionsPrefix(Vec v,const char prefix[])
1593: {

1598:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1599:   return(0);
1600: }

1604: /*@C
1605:    VecGetOptionsPrefix - Sets the prefix used for searching for all
1606:    Vec options in the database.

1608:    Not Collective

1610:    Input Parameter:
1611: .  v - the Vec context

1613:    Output Parameter:
1614: .  prefix - pointer to the prefix string used

1616:    Notes: On the fortran side, the user should pass in a string 'prefix' of
1617:    sufficient length to hold the prefix.

1619:    Level: advanced

1621: .keywords: Vec, get, options, prefix, database

1623: .seealso: VecAppendOptionsPrefix()
1624: @*/
1625: PetscErrorCode  VecGetOptionsPrefix(Vec v,const char *prefix[])
1626: {

1631:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1632:   return(0);
1633: }

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

1640:    Collective on Vec

1642:    Input Parameters:
1643: .  v - the Vec context

1645:    Notes:
1646:    For basic use of the Vec classes the user need not explicitly call
1647:    VecSetUp(), since these actions will happen automatically.

1649:    Level: advanced

1651: .keywords: Vec, setup

1653: .seealso: VecCreate(), VecDestroy()
1654: @*/
1655: PetscErrorCode  VecSetUp(Vec v)
1656: {
1657:   PetscMPIInt    size;

1662:   if (!((PetscObject)v)->type_name) {
1663:     MPI_Comm_size(((PetscObject)v)->comm, &size);
1664:     if (size == 1) {
1665:       VecSetType(v, VECSEQ);
1666:     } else {
1667:       VecSetType(v, VECMPI);
1668:     }
1669:   }
1670:   return(0);
1671: }

1673: /*
1674:     These currently expose the PetscScalar/PetscReal in updating the
1675:     cached norm. If we push those down into the implementation these
1676:     will become independent of PetscScalar/PetscReal
1677: */

1681: /*@
1682:    VecCopy - Copies a vector. y <- x

1684:    Logically Collective on Vec

1686:    Input Parameter:
1687: .  x - the vector

1689:    Output Parameter:
1690: .  y - the copy

1692:    Notes:
1693:    For default parallel PETSc vectors, both x and y must be distributed in
1694:    the same manner; local copies are done.

1696:    Level: beginner

1698: .seealso: VecDuplicate()
1699: @*/
1700: PetscErrorCode  VecCopy(Vec x,Vec y)
1701: {
1702:   PetscBool      flgs[4];
1703:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
1705:   PetscInt       i;

1712:   if (x == y) return(0);
1713:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1714:   if (x->map->n != y->map->n) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths %d != %d", x->map->n, y->map->n);

1716: #if !defined(PETSC_USE_MIXED_PRECISION)
1717:   for (i=0; i<4; i++) {
1718:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
1719:   }
1720: #endif

1722:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1723: #if defined(PETSC_USE_MIXED_PRECISION)
1732:   if ((((PetscObject)x)->precision == PETSC_PRECISION_SINGLE) && (((PetscObject)y)->precision == PETSC_PRECISION_DOUBLE)) {
1733:     PetscInt    i,n;
1734:     const float *xx;
1735:     double      *yy;
1736:     VecGetArrayRead(x,&xx);
1737:     VecGetArray(y,&yy);
1738:     VecGetLocalSize(x,&n);
1739:     for (i=0; i<n; i++) {
1740:       yy[i] = xx[i];
1741:     }
1742:     VecRestoreArrayRead(x,&xx);
1743:     VecRestoreArray(y,&yy);
1744:   } else if ((((PetscObject)x)->precision == PETSC_PRECISION_DOUBLE) && (((PetscObject)y)->precision == PETSC_PRECISION_SINGLE)) {
1745:     PetscInt     i,n;
1746:     float        *yy;
1747:     const double *xx;
1748:     VecGetArrayRead(x,&xx);
1749:     VecGetArray(y,&yy);
1750:     VecGetLocalSize(x,&n);
1751:     for (i=0; i<n; i++) {
1752:       yy[i] = (float) xx[i];
1753:     }
1754:     VecRestoreArrayRead(x,&xx);
1755:     VecRestoreArray(y,&yy);
1756:   } else {
1757:     (*x->ops->copy)(x,y);
1758:   }
1759: #else
1760:   (*x->ops->copy)(x,y);
1761: #endif

1763:   PetscObjectStateIncrease((PetscObject)y);
1764: #if !defined(PETSC_USE_MIXED_PRECISION)
1765:   for (i=0; i<4; i++) {
1766:     if (flgs[i]) {
1767:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
1768:     }
1769:   }
1770: #endif

1772:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1773:   return(0);
1774: }

1778: /*@
1779:    VecSwap - Swaps the vectors x and y.

1781:    Logically Collective on Vec

1783:    Input Parameters:
1784: .  x, y  - the vectors

1786:    Level: advanced

1788:    Concepts: vector^swapping values

1790: @*/
1791: PetscErrorCode  VecSwap(Vec x,Vec y)
1792: {
1793:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
1794:   PetscBool      flgxs[4],flgys[4];
1796:   PetscInt       i;

1804:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1805:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1806:   if (x->map->N != y->map->N) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1807:   if (x->map->n != y->map->n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1809:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1810:   for (i=0; i<4; i++) {
1811:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
1812:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
1813:   }
1814:   (*x->ops->swap)(x,y);
1815:   PetscObjectStateIncrease((PetscObject)x);
1816:   PetscObjectStateIncrease((PetscObject)y);
1817:   for (i=0; i<4; i++) {
1818:     if (flgxs[i]) {
1819:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
1820:     }
1821:     if (flgys[i]) {
1822:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
1823:     }
1824:   }
1825:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
1826:   return(0);
1827: }

1831: /*@
1832:    VecStashView - Prints the entries in the vector stash and block stash.

1834:    Collective on Vec

1836:    Input Parameters:
1837: +  v - the vector
1838: -  viewer - the viewer

1840:    Level: advanced

1842:    Concepts: vector^stash
1843:    Concepts: stash^vector

1845: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()

1847: @*/
1848: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
1849: {
1851:   PetscMPIInt    rank;
1852:   PetscInt       i,j;
1853:   PetscBool      match;
1854:   VecStash       *s;
1855:   PetscScalar    val;


1862:   PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&match);
1863:   if (!match) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
1864:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
1865:   MPI_Comm_rank(((PetscObject)v)->comm,&rank);
1866:   s = &v->bstash;

1868:   /* print block stash */
1869:   PetscViewerASCIISynchronizedAllow(viewer,PETSC_TRUE);
1870:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
1871:   for (i=0; i<s->n; i++) {
1872:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
1873:     for (j=0; j<s->bs; j++) {
1874:       val = s->array[i*s->bs+j];
1875: #if defined(PETSC_USE_COMPLEX)
1876:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
1877: #else
1878:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
1879: #endif
1880:     }
1881:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
1882:   }
1883:   PetscViewerFlush(viewer);

1885:   s = &v->stash;

1887:   /* print basic stash */
1888:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
1889:   for (i=0; i<s->n; i++) {
1890:     val = s->array[i];
1891: #if defined(PETSC_USE_COMPLEX)
1892:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
1893: #else
1894:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
1895: #endif
1896:   }
1897:   PetscViewerFlush(viewer);
1898:   PetscViewerASCIISynchronizedAllow(viewer,PETSC_FALSE);

1900:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1901:   return(0);
1902: }