Actual source code: vector.c

  1: #define PETSCVEC_DLL

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

  9: /* Logging support */
 10: PetscCookie PETSCVEC_DLLEXPORT VEC_COOKIE = 0;
 11: PetscEvent  VEC_View = 0, VEC_Max = 0, VEC_Min = 0, VEC_DotBarrier = 0, VEC_Dot = 0, VEC_MDotBarrier = 0, VEC_MDot = 0, VEC_TDot = 0;
 12: PetscEvent  VEC_Norm = 0, VEC_Normalize = 0, VEC_Scale = 0, VEC_Copy = 0, VEC_Set = 0, VEC_AXPY = 0, VEC_AYPX = 0, VEC_WAXPY = 0;
 13: PetscEvent  VEC_MTDot = 0, VEC_NormBarrier = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
 14: PetscEvent  VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0;
 15: PetscEvent  VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;

 17: EXTERN PetscErrorCode VecStashGetInfo_Private(VecStash*,PetscInt*,PetscInt*);
 20: /*@ 
 21:    VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
 22:        to be communicated to other processors during the VecAssemblyBegin/End() process

 24:     Not collective

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

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

 37: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
 38:   
 39: @*/
 40: PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
 41: {
 44:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
 45:   VecStashGetInfo_Private(&vec->bstash,nstash,reallocs);
 46:   return(0);
 47: }

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

 56:    Collective on Vec

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

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

 65:    Level: intermediate

 67:    Concepts: vector^setting values with local numbering

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


 80:   if (x->mapping) {
 81:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
 82:   }

 84:   if (x->ops->setlocaltoglobalmapping) {
 85:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
 86:   } else {
 87:     x->mapping = mapping;
 88:     PetscObjectReference((PetscObject)mapping);
 89:   }
 90:   return(0);
 91: }

 95: /*@
 96:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
 97:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
 98:    using a local (per-processor) numbering.

100:    Collective on Vec

102:    Input Parameters:
103: +  x - vector
104: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

109:    Level: intermediate

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

113: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
114:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
115: @*/
116: PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
117: {


124:   if (x->bmapping) {
125:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
126:   }
127:   x->bmapping = mapping;
128:   PetscObjectReference((PetscObject)mapping);
129:   return(0);
130: }

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

138:    Collective on Vec

140:    Input Parameter:
141: .  vec - the vector

143:    Level: beginner

145:    Concepts: assembly^vectors

147: .seealso: VecAssemblyEnd(), VecSetValues()
148: @*/
149: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec vec)
150: {
152:   PetscTruth     flg;


158:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
159:   if (flg) {
160:     VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
161:   }

163:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
164:   if (vec->ops->assemblybegin) {
165:     (*vec->ops->assemblybegin)(vec);
166:   }
167:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
168:   PetscObjectStateIncrease((PetscObject)vec);
169:   return(0);
170: }

174: /*@
175:    VecAssemblyEnd - Completes assembling the vector.  This routine should
176:    be called after VecAssemblyBegin().

178:    Collective on Vec

180:    Input Parameter:
181: .  vec - the vector

183:    Options Database Keys:
184: +  -vec_view - Prints vector in ASCII format
185: .  -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
186: .  -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
187: .  -vec_view_draw - Activates vector viewing using drawing tools
188: .  -display <name> - Sets display name (default is host)
189: .  -draw_pause <sec> - Sets number of seconds to pause after display
190: -  -vec_view_socket - Activates vector viewing using a socket
191:  
192:    Level: beginner

194: .seealso: VecAssemblyBegin(), VecSetValues()
195: @*/
196: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec vec)
197: {
199:   PetscTruth     flg;

203:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
205:   if (vec->ops->assemblyend) {
206:     (*vec->ops->assemblyend)(vec);
207:   }
208:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
209:   PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
210:     PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
211:     if (flg) {
212:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
213:     }
214:     PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
215:     if (flg) {
216:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
217:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
218:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
219:     }
220: #if defined(PETSC_HAVE_MATLAB)
221:     PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
222:     if (flg) {
223:       VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
224:     }
225: #endif
226: #if defined(PETSC_USE_SOCKET_VIEWER)
227:     PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
228:     if (flg) {
229:       VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
230:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
231:     }
232: #endif
233:     PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
234:     if (flg) {
235:       VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
236:       PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
237:     }
238:   PetscOptionsEnd();
239:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
240:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
241:   PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
242:   if (flg) {
243:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
244:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
245:   }
246:   PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
247:   if (flg) {
248:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
249:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
250:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
251:   }
252:   return(0);
253: }

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

260:    Collective on Vec

262:    Input Parameters:
263: .  x, y  - the vectors

265:    Output Parameter:
266: .  w - the result

268:    Level: advanced

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

273:    Concepts: vector^pointwise multiply

275: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
276: @*/
277: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMax(Vec w,Vec x,Vec y)
278: {

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

293:   (*w->ops->pointwisemax)(w,x,y);
294:   PetscObjectStateIncrease((PetscObject)w);
295:   return(0);
296: }


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

304:    Collective on Vec

306:    Input Parameters:
307: .  x, y  - the vectors

309:    Output Parameter:
310: .  w - the result

312:    Level: advanced

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

317:    Concepts: vector^pointwise multiply

319: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
320: @*/
321: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMin(Vec w,Vec x,Vec y)
322: {

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

337:   (*w->ops->pointwisemin)(w,x,y);
338:   PetscObjectStateIncrease((PetscObject)w);
339:   return(0);
340: }

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

347:    Collective on Vec

349:    Input Parameters:
350: .  x, y  - the vectors

352:    Output Parameter:
353: .  w - the result

355:    Level: advanced

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

359:    Concepts: vector^pointwise multiply

361: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
362: @*/
363: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
364: {

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

379:   (*w->ops->pointwisemaxabs)(w,x,y);
380:   PetscObjectStateIncrease((PetscObject)w);
381:   return(0);
382: }

386: /*@
387:    VecPointwiseDivide - Computes the componentwise division w = x/y.

389:    Collective on Vec

391:    Input Parameters:
392: .  x, y  - the vectors

394:    Output Parameter:
395: .  w - the result

397:    Level: advanced

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

401:    Concepts: vector^pointwise divide

403: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
404: @*/
405: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseDivide(Vec w,Vec x,Vec y)
406: {

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

421:   (*w->ops->pointwisedivide)(w,x,y);
422:   PetscObjectStateIncrease((PetscObject)w);
423:   return(0);
424: }


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

432:    Collective on Vec

434:    Input Parameters:
435: .  v - a vector to mimic

437:    Output Parameter:
438: .  newv - location to put new vector

440:    Notes:
441:    VecDuplicate() does not copy the vector, but rather allocates storage
442:    for the new vector.  Use VecCopy() to copy a vector.

444:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
445:    vectors. 

447:    Level: beginner

449: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
450: @*/
451: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicate(Vec x,Vec *newv)
452: {

459:   (*x->ops->duplicate)(x,newv);
460:   PetscObjectStateIncrease((PetscObject)*newv);
461:   return(0);
462: }

466: /*@
467:    VecDestroy - Destroys a vector.

469:    Collective on Vec

471:    Input Parameters:
472: .  v  - the vector

474:    Level: beginner

476: .seealso: VecDuplicate(), VecDestroyVecs()
477: @*/
478: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroy(Vec v)
479: {

484:   if (--v->refct > 0) return(0);
485:   /* destroy the internal part */
486:   if (v->ops->destroy) {
487:     (*v->ops->destroy)(v);
488:   }
489:   /* destroy the external/common part */
490:   if (v->mapping) {
491:     ISLocalToGlobalMappingDestroy(v->mapping);
492:   }
493:   if (v->bmapping) {
494:     ISLocalToGlobalMappingDestroy(v->bmapping);
495:   }
496:   PetscFree(v->map.range);
497:   PetscHeaderDestroy(v);
498:   return(0);
499: }

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

506:    Collective on Vec

508:    Input Parameters:
509: +  m - the number of vectors to obtain
510: -  v - a vector to mimic

512:    Output Parameter:
513: .  V - location to put pointer to array of vectors

515:    Notes:
516:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
517:    vector.

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

524:    Level: intermediate

526: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
527: @*/
528: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
529: {

536:   (*v->ops->duplicatevecs)(v, m,V);
537:   return(0);
538: }

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

545:    Collective on Vec

547:    Input Parameters:
548: +  vv - pointer to array of vector pointers
549: -  m - the number of vectors previously obtained

551:    Fortran Note:
552:    The Fortran interface is slightly different from that given below.
553:    See the Fortran chapter of the users manual and 
554:    petsc/src/vec/examples for details.

556:    Level: intermediate

558: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
559: @*/
560: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroyVecs(Vec vv[],PetscInt m)
561: {

568:   (*(*vv)->ops->destroyvecs)(vv,m);
569:   return(0);
570: }

572: #undef  __FUNCT__
574: /*@
575:   VecViewFromOptions - This function visualizes the vector based upon user options.

577:   Collective on Vec

579:   Input Parameters:
580: . vec   - The vector
581: . title - The title

583:   Level: intermediate

585: .keywords: Vec, view, options, database
586: .seealso: VecSetFromOptions(), VecView()
587: @*/
588: PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec vec, char *title)
589: {
590:   PetscViewer    viewer;
591:   PetscDraw      draw;
592:   PetscTruth     opt;
593:   char           *titleStr;
594:   char           typeName[1024];
595:   char           fileName[PETSC_MAX_PATH_LEN];
596:   size_t         len;

600:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
601:   if (opt) {
602:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
603:     PetscStrlen(typeName, &len);
604:     if (len > 0) {
605:       PetscViewerCreate(vec->comm, &viewer);
606:       PetscViewerSetType(viewer, typeName);
607:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
608:       if (opt) {
609:         PetscViewerFileSetName(viewer, fileName);
610:       } else {
611:         PetscViewerFileSetName(viewer, vec->name);
612:       }
613:       VecView(vec, viewer);
614:       PetscViewerFlush(viewer);
615:       PetscViewerDestroy(viewer);
616:     } else {
617:       VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
618:     }
619:   }
620:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
621:   if (opt) {
622:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
623:     PetscViewerDrawGetDraw(viewer, 0, &draw);
624:     if (title) {
625:       titleStr = title;
626:     } else {
627:       PetscObjectName((PetscObject) vec);
628:       titleStr = vec->name;
629:     }
630:     PetscDrawSetTitle(draw, titleStr);
631:     VecView(vec, viewer);
632:     PetscViewerFlush(viewer);
633:     PetscDrawPause(draw);
634:     PetscViewerDestroy(viewer);
635:   }
636:   return(0);
637: }

641: /*@C
642:    VecView - Views a vector object. 

644:    Collective on Vec

646:    Input Parameters:
647: +  v - the vector
648: -  viewer - an optional visualization context

650:    Notes:
651:    The available visualization contexts include
652: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
653: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
654:          output where only the first processor opens
655:          the file.  All other processors send their 
656:          data to the first processor to print. 

658:    You can change the format the vector is printed using the 
659:    option PetscViewerSetFormat().

661:    The user can open alternative visualization contexts with
662: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
663: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
664:          specified file; corresponding input uses VecLoad()
665: .    PetscViewerDrawOpen() - Outputs vector to an X window display
666: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

668:    The user can call PetscViewerSetFormat() to specify the output
669:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
670:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
671: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
672: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
673: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
674: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
675:          format common among all vector types

677:    Level: beginner

679:    Concepts: vector^printing
680:    Concepts: vector^saving to disk

682: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
683:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
684:           PetscRealView(), PetscScalarView(), PetscIntView()
685: @*/
686: PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec vec,PetscViewer viewer)
687: {
688:   PetscErrorCode    ierr;
689:   PetscViewerFormat format;

694:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
697:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

699:   /*
700:      Check if default viewer has been overridden, but user request it anyways
701:   */
702:   PetscViewerGetFormat(viewer,&format);
703:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
704:     PetscViewerPopFormat(viewer);
705:     (*vec->ops->viewnative)(vec,viewer);
706:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
707:   } else {
708:     (*vec->ops->view)(vec,viewer);
709:   }
710:   return(0);
711: }

715: /*@
716:    VecGetSize - Returns the global number of elements of the vector.

718:    Not Collective

720:    Input Parameter:
721: .  x - the vector

723:    Output Parameters:
724: .  size - the global length of the vector

726:    Level: beginner

728:    Concepts: vector^local size

730: .seealso: VecGetLocalSize()
731: @*/
732: PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec x,PetscInt *size)
733: {

740:   (*x->ops->getsize)(x,size);
741:   return(0);
742: }

746: /*@
747:    VecGetLocalSize - Returns the number of elements of the vector stored 
748:    in local memory. This routine may be implementation dependent, so use 
749:    with care.

751:    Not Collective

753:    Input Parameter:
754: .  x - the vector

756:    Output Parameter:
757: .  size - the length of the local piece of the vector

759:    Level: beginner

761:    Concepts: vector^size

763: .seealso: VecGetSize()
764: @*/
765: PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec x,PetscInt *size)
766: {

773:   (*x->ops->getlocalsize)(x,size);
774:   return(0);
775: }

779: /*@C
780:    VecGetOwnershipRange - Returns the range of indices owned by 
781:    this processor, assuming that the vectors are laid out with the
782:    first n1 elements on the first processor, next n2 elements on the
783:    second, etc.  For certain parallel layouts this range may not be 
784:    well defined. 

786:    Not Collective

788:    Input Parameter:
789: .  x - the vector

791:    Output Parameters:
792: +  low - the first local element, pass in PETSC_NULL if not interested
793: -  high - one more than the last local element, pass in PETSC_NULL if not interested

795:    Note:
796:    The high argument is one more than the last element stored locally.

798:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

800:    Level: beginner

802:    Concepts: ownership^of vectors
803:    Concepts: vector^ownership of elements

805: @*/
806: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
807: {
813:   if (low)  *low  = x->map.rstart;
814:   if (high) *high = x->map.rend;
815:   return(0);
816: }

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

823:    Collective on Vec

825:    Input Parameter:
826: +  x - the vector
827: -  op - the option

829:    Supported Options:
830: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
831:       entries destined to be stored on a separate processor. This can be used
832:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
833:       that you have only used VecSetValues() to set local elements
834: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

836:    Level: intermediate

838: @*/
839: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec x,VecOption op)
840: {

846:   if (x->ops->setoption) {
847:     (*x->ops->setoption)(x,op);
848:   }
849:   return(0);
850: }

854: /* Default routines for obtaining and releasing; */
855: /* may be used by any implementation */
856: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
857: {
859:   PetscInt       i;

864:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
865:   PetscMalloc(m*sizeof(Vec*),V);
866:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
867:   return(0);
868: }

872: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
873: {
875:   PetscInt       i;

879:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
880:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
881:   PetscFree(v);
882:   return(0);
883: }

887: /*@
888:    VecResetArray - Resets a vector to use its default memory. Call this 
889:    after the use of VecPlaceArray().

891:    Not Collective

893:    Input Parameters:
894: .  vec - the vector

896:    Level: developer

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

900: @*/
901: PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec vec)
902: {

908:   if (vec->ops->resetarray) {
909:     (*vec->ops->resetarray)(vec);
910:   } else {
911:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
912:   }
913:   PetscObjectStateIncrease((PetscObject)vec);
914:   return(0);
915: }

919: /*@C 
920:   VecLoadIntoVector - Loads a vector that has been stored in binary format
921:   with VecView().

923:   Collective on PetscViewer 

925:   Input Parameters:
926: + viewer - binary file viewer, obtained from PetscViewerBinaryOpen()
927: - vec - vector to contain files values (must be of correct length)

929:   Level: intermediate

931:   Notes:
932:   The input file must contain the full global vector, as
933:   written by the routine VecView().

935:   Use VecLoad() to create the vector as the values are read in

937:   Notes for advanced users:
938:   Most users should not need to know the details of the binary storage
939:   format, since VecLoad() and VecView() completely hide these details.
940:   But for anyone who's interested, the standard binary matrix storage
941:   format is
942: .vb
943:      int    VEC_FILE_COOKIE
944:      int    number of rows
945:      PetscScalar *values of all nonzeros
946: .ve

948:    Note for Cray users, the int's stored in the binary file are 32 bit
949: integers; not 64 as they are represented in the memory, so if you
950: write your own routines to read/write these binary files from the Cray
951: you need to adjust the integer sizes that you read in, see
952: PetscBinaryRead() and PetscBinaryWrite() to see how this may be
953: done.

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

961:    Concepts: vector^loading from file

963: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
964: @*/
965: PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer viewer,Vec vec)
966: {

973:   if (!vec->ops->loadintovector) {
974:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
975:   }
976:   (*vec->ops->loadintovector)(viewer,vec);
977:   PetscObjectStateIncrease((PetscObject)vec);
978:   return(0);
979: }

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

986:    Collective on Vec

988:    Input Parameter:
989: .  v - the vector 

991:    Output Parameter:
992: .  v - the vector reciprocal

994:    Level: intermediate

996:    Concepts: vector^reciprocal

998: @*/
999: PetscErrorCode PETSCVEC_DLLEXPORT VecReciprocal(Vec vec)
1000: {

1006:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1007:   if (!vec->ops->reciprocal) {
1008:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
1009:   }
1010:   (*vec->ops->reciprocal)(vec);
1011:   PetscObjectStateIncrease((PetscObject)vec);
1012:   return(0);
1013: }

1017: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
1018: {
1021:   /* save the native version of the viewer */
1022:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
1023:     vec->ops->viewnative = vec->ops->view;
1024:   }
1025:   (((void(**)(void))vec->ops)[(int)op]) = f;
1026:   return(0);
1027: }


1032: /*@
1033:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1034:    used during the assembly process to store values that belong to 
1035:    other processors.

1037:    Collective on Vec

1039:    Input Parameters:
1040: +  vec   - the vector
1041: .  size  - the initial size of the stash.
1042: -  bsize - the initial size of the block-stash(if used).

1044:    Options Database Keys:
1045: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1046: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1048:    Level: intermediate

1050:    Notes: 
1051:      The block-stash is used for values set with VecSetValuesBlocked() while
1052:      the stash is used for values set with VecSetValues()

1054:      Run with the option -info and look for output of the form
1055:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
1056:      to determine the appropriate value, MM, to use for size and 
1057:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
1058:      to determine the value, BMM to use for bsize

1060:    Concepts: vector^stash
1061:    Concepts: stash^vector

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

1065: @*/
1066: PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1067: {

1072:   VecStashSetInitialSize_Private(&vec->stash,size);
1073:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1074:   return(0);
1075: }

1079: /*@
1080:    VecConjugate - Conjugates a vector.

1082:    Collective on Vec

1084:    Input Parameters:
1085: .  x - the vector

1087:    Level: intermediate

1089:    Concepts: vector^conjugate

1091: @*/
1092: PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec x)
1093: {
1094: #ifdef PETSC_USE_COMPLEX

1100:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1101:   (*x->ops->conjugate)(x);
1102:   /* we need to copy norms here */
1103:   PetscObjectStateIncrease((PetscObject)x);
1104:   return(0);
1105: #else
1106:   return(0);
1107: #endif
1108: }

1112: /*@
1113:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1115:    Collective on Vec

1117:    Input Parameters:
1118: .  x, y  - the vectors

1120:    Output Parameter:
1121: .  w - the result

1123:    Level: advanced

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

1127:    Concepts: vector^pointwise multiply

1129: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1130: @*/
1131: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMult(Vec w, Vec x,Vec y)
1132: {

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

1147:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1148:   (*w->ops->pointwisemult)(w,x,y);
1149:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1150:   PetscObjectStateIncrease((PetscObject)w);
1151:   return(0);
1152: }

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

1159:    Collective on Vec

1161:    Input Parameters:
1162: +  x  - the vector
1163: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1164:           it will create one internally.

1166:    Output Parameter:
1167: .  x  - the vector

1169:    Example of Usage:
1170: .vb
1171:      PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
1172:      VecSetRandom(x,rctx);
1173:      PetscRandomDestroy(rctx);
1174: .ve

1176:    Level: intermediate

1178:    Concepts: vector^setting to random
1179:    Concepts: random^vector

1181: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1182: @*/
1183: PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec x,PetscRandom rctx)
1184: {
1186:   PetscRandom    randObj = PETSC_NULL;

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

1194:   if (!rctx) {
1195:     MPI_Comm    comm;
1196:     PetscObjectGetComm((PetscObject)x,&comm);
1197:     PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
1198:     rctx = randObj;
1199:   }

1201:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1202:   (*x->ops->setrandom)(x,rctx);
1203:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
1204: 
1205:   if (randObj) {
1206:     PetscRandomDestroy(randObj);
1207:   }
1208:   PetscObjectStateIncrease((PetscObject)x);
1209:   return(0);
1210: }

1212: /*@
1213:   VecZeroEntries - puts a 0.0 in each element of a vector

1215:   Collective on Vec

1217:   Input Parameter:
1218: . vec - The vector

1220:   Level: beginner

1222: .keywords: Vec, set, options, database
1223: .seealso: VecCreate(), VecPrintHelp(), VecSetOptionsPrefix(), VecSet(), VecSetValues()
1224: @*/
1225: PetscErrorCode PETSCVEC_DLLEXPORT VecZeroEntries (Vec vec)
1226: {
1229:   VecSet(vec,0);
1230:   return(0);
1231: }

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

1239:   Collective on Vec

1241:   Input Parameter:
1242: . vec - The vector

1244:   Level: intermediate

1246: .keywords: Vec, set, options, database, type
1247: .seealso: VecSetFromOptions(), VecSetType()
1248: */
1249: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
1250: {
1251:   PetscTruth     opt;
1252:   const char     *defaultType;
1253:   char           typeName[256];
1254:   PetscMPIInt    size;

1258:   if (vec->type_name) {
1259:     defaultType = vec->type_name;
1260:   } else {
1261:     MPI_Comm_size(vec->comm, &size);
1262:     if (size > 1) {
1263:       defaultType = VECMPI;
1264:     } else {
1265:       defaultType = VECSEQ;
1266:     }
1267:   }

1269:   if (!VecRegisterAllCalled) {
1270:     VecRegisterAll(PETSC_NULL);
1271:   }
1272:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
1273:   if (opt) {
1274:     VecSetType(vec, typeName);
1275:   } else {
1276:     VecSetType(vec, defaultType);
1277:   }
1278:   return(0);
1279: }

1283: /*@
1284:   VecSetFromOptions - Configures the vector from the options database.

1286:   Collective on Vec

1288:   Input Parameter:
1289: . vec - The vector

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

1294:   Level: beginner

1296:   Concepts: vectors^setting options
1297:   Concepts: vectors^setting type

1299: .keywords: Vec, set, options, database
1300: .seealso: VecCreate(), VecPrintHelp(), VecSetOptionsPrefix()
1301: @*/
1302: PetscErrorCode PETSCVEC_DLLEXPORT VecSetFromOptions(Vec vec)
1303: {
1304:   PetscTruth     opt;


1310:   PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");

1312:   /* Handle generic vector options */
1313:   PetscOptionsHasName(PETSC_NULL, "-help", &opt);
1314:   if (opt) {
1315:     VecPrintHelp(vec);
1316:   }

1318:   /* Handle vector type options */
1319:   VecSetTypeFromOptions_Private(vec);

1321:   /* Handle specific vector options */
1322:   if (vec->ops->setfromoptions) {
1323:     (*vec->ops->setfromoptions)(vec);
1324:   }
1325:   PetscOptionsEnd();

1327:   VecViewFromOptions(vec, vec->name);
1328:   return(0);
1329: }

1333: /*@
1334:   VecPrintHelp - Prints some options for the Vec.

1336:   Input Parameter:
1337: . vec - The vector

1339:   Options Database Keys:
1340: $  -help, -h

1342:   Level: intermediate

1344: .keywords: Vec, help
1345: .seealso: VecSetFromOptions()
1346: @*/
1347: PetscErrorCode PETSCVEC_DLLEXPORT VecPrintHelp(Vec vec)
1348: {
1351:   return(0);
1352: }

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

1359:   Collective on Vec

1361:   Input Parameters:
1362: + v - the vector
1363: . n - the local size (or PETSC_DECIDE to have it set)
1364: - N - the global size (or PETSC_DECIDE)

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

1370:   Level: intermediate

1372: .seealso: VecGetSize(), PetscSplitOwnership()
1373: @*/
1374: PetscErrorCode PETSCVEC_DLLEXPORT VecSetSizes(Vec v, PetscInt n, PetscInt N)
1375: {
1378:   if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
1379:   if ((v->map.n >= 0 || v->map.N >= 0) && (v->map.n != n || v->map.N != N)) SETERRQ4(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);
1380:   v->map.n = n;
1381:   v->map.N = N;
1382:   return(0);
1383: }

1387: /*@
1388:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
1389:    and VecSetValuesBlockedLocal().

1391:    Collective on Vec

1393:    Input Parameter:
1394: +  v - the vector
1395: -  bs - the blocksize

1397:    Notes:
1398:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1400:    Level: advanced

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

1404:   Concepts: block size^vectors
1405: @*/
1406: PetscErrorCode PETSCVEC_DLLEXPORT VecSetBlockSize(Vec v,PetscInt bs)
1407: {
1410:   if (bs <= 0) bs = 1;
1411:   if (bs == v->map.bs) return(0);
1412:   if (v->map.N != -1 && v->map.N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %D %D",v->map.N,bs);
1413:   if (v->map.n != -1 && v->map.n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
1414:    Try setting blocksize before setting the vector type",v->map.n,bs);
1415: 
1416:   v->map.bs    = bs;
1417:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
1418:   return(0);
1419: }

1423: /*@
1424:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
1425:    and VecSetValuesBlockedLocal().

1427:    Collective on Vec

1429:    Input Parameter:
1430: .  v - the vector

1432:    Output Parameter:
1433: .  bs - the blocksize

1435:    Notes:
1436:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1438:    Level: advanced

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

1442:    Concepts: vector^block size
1443:    Concepts: block^vector

1445: @*/
1446: PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec v,PetscInt *bs)
1447: {
1451:   *bs = v->map.bs;
1452:   return(0);
1453: }

1457: /*@
1458:    VecValid - Checks whether a vector object is valid.

1460:    Not Collective

1462:    Input Parameter:
1463: .  v - the object to check

1465:    Output Parameter:
1466:    flg - flag indicating vector status, either
1467:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

1469:    Level: developer

1471: @*/
1472: PetscErrorCode PETSCVEC_DLLEXPORT VecValid(Vec v,PetscTruth *flg)
1473: {
1476:   if (!v)                           *flg = PETSC_FALSE;
1477:   else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
1478:   else                              *flg = PETSC_TRUE;
1479:   return(0);
1480: }

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

1488:    Collective on Vec

1490:    Input Parameter:
1491: +  v - the Vec context
1492: -  prefix - the prefix to prepend to all option names

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

1498:    Level: advanced

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

1502: .seealso: VecSetFromOptions()
1503: @*/
1504: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOptionsPrefix(Vec v,const char prefix[])
1505: {

1510:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1511:   return(0);
1512: }

1516: /*@C
1517:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all 
1518:    Vec options in the database.

1520:    Collective on Vec

1522:    Input Parameters:
1523: +  v - the Vec context
1524: -  prefix - the prefix to prepend to all option names

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

1530:    Level: advanced

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

1534: .seealso: VecGetOptionsPrefix()
1535: @*/
1536: PetscErrorCode PETSCVEC_DLLEXPORT VecAppendOptionsPrefix(Vec v,const char prefix[])
1537: {
1539: 
1542:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1543:   return(0);
1544: }

1548: /*@C
1549:    VecGetOptionsPrefix - Sets the prefix used for searching for all 
1550:    Vec options in the database.

1552:    Not Collective

1554:    Input Parameter:
1555: .  A - the Vec context

1557:    Output Parameter:
1558: .  prefix - pointer to the prefix string used

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

1563:    Level: advanced

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

1567: .seealso: VecAppendOptionsPrefix()
1568: @*/
1569: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOptionsPrefix(Vec v,const char *prefix[])
1570: {

1575:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1576:   return(0);
1577: }

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

1584:    Collective on Vec

1586:    Input Parameters:
1587: .  v - the Vec context

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

1593:    Level: advanced

1595: .keywords: Vec, setup

1597: .seealso: VecCreate(), VecDestroy()
1598: @*/
1599: PetscErrorCode PETSCVEC_DLLEXPORT VecSetUp(Vec v)
1600: {

1605:   VecSetFromOptions(v);
1606:   return(0);
1607: }

1609: /*  
1610:     These currently expose the PetscScalar/PetscReal in updating the
1611:     cached norm. If we push those down into the implementation these
1612:     will become independent of PetscScalar/PetscReal
1613: */

1617: /*@
1618:    VecCopy - Copies a vector. 

1620:    Collective on Vec

1622:    Input Parameter:
1623: .  x - the vector

1625:    Output Parameter:
1626: .  y - the copy

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

1632:    Level: beginner

1634: .seealso: VecDuplicate()
1635: @*/
1636: PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec x,Vec y)
1637: {
1638:   PetscTruth     flgs[4];
1639:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
1641:   PetscInt       i;

1649:   if (x == y) return(0);
1650:   if (x->map.N != y->map.N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1651:   if (x->map.n != y->map.n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1653:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1654:   (*x->ops->copy)(x,y);


1657:   /*
1658:    * Update cached data
1659:   */
1660:   /* in general we consider this object touched */
1661:   PetscObjectStateIncrease((PetscObject)y);

1663:   for (i=0; i<4; i++) {
1664:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
1665:   }
1666:   for (i=0; i<4; i++) {
1667:     if (flgs[i]) {
1668:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
1669:     }
1670:   }

1672:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1673:   return(0);
1674: }

1678: /*@
1679:    VecSwap - Swaps the vectors x and y.

1681:    Collective on Vec

1683:    Input Parameters:
1684: .  x, y  - the vectors

1686:    Level: advanced

1688:    Concepts: vector^swapping values

1690: @*/
1691: PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec x,Vec y)
1692: {
1693:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
1694:   PetscTruth     flgxs[4],flgys[4];
1696:   PetscInt       i;

1704:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1705:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1706:   if (x->map.N != y->map.N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1707:   if (x->map.n != y->map.n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1709:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1710:   (*x->ops->swap)(x,y);

1712:   /* See if we have cached norms */
1713:   for (i=0; i<4; i++) {
1714:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
1715:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
1716:   }
1717:   for (i=0; i<4; i++) {
1718:     if (flgxs[i]) {
1719:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
1720:     }
1721:     if (flgys[i]) {
1722:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
1723:     }
1724:   }
1725:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
1726:   return(0);
1727: }

1731: /*@
1732:    VecStashView - Prints the entries in the vector stash and block stash.

1734:    Collective on Vec

1736:    Input Parameters:
1737: +  vec   - the vector
1738: -  viewer - the viewer

1740:    Level: advanced

1742:    Concepts: vector^stash
1743:    Concepts: stash^vector

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

1747: @*/
1748: PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec v,PetscViewer viewer)
1749: {
1751:   PetscMPIInt    rank;
1752:   PetscInt       i,j;
1753:   PetscTruth     match;
1754:   VecStash       *s;
1755:   PetscScalar    val;


1762:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
1763:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
1764:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
1765:   MPI_Comm_rank(v->comm,&rank);
1766:   s = &v->bstash;

1768:   /* print block stash */
1769:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
1770:   for (i=0; i<s->n; i++) {
1771:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
1772:     for (j=0; j<s->bs; j++) {
1773:       val = s->array[i*s->bs+j];
1774: #if defined(PETSC_USE_COMPLEX)
1775:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
1776: #else
1777:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
1778: #endif
1779:     }
1780:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
1781:   }
1782:   PetscViewerFlush(viewer);

1784:   s = &v->stash;

1786:   /* print basic stash */
1787:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
1788:   for (i=0; i<s->n; i++) {
1789:     val = s->array[i];
1790: #if defined(PETSC_USE_COMPLEX)
1791:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
1792: #else
1793:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
1794: #endif
1795:   }
1796:   PetscViewerFlush(viewer);

1798:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1799:   return(0);
1800: }