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  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;
 16: PetscEvent  VEC_DotNormBarrier = 0, VEC_DotNorm = 0;

 18: EXTERN PetscErrorCode VecStashGetInfo_Private(VecStash*,PetscInt*,PetscInt*);
 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
 35:  
 36:    Level: advanced

 38: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
 39:   
 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:    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->mapping) {
 82:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
 83:   }

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

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

102:    Collective on Vec

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

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

111:    Level: intermediate

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

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


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

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

141:    Collective on Vec

143:    Input Parameter:
144: .  vec - the vector

146:    Level: beginner

148:    Concepts: assembly^vectors

150: .seealso: VecAssemblyEnd(), VecSetValues()
151: @*/
152: PetscErrorCode  VecAssemblyBegin(Vec vec)
153: {
155:   PetscTruth     flg;


161:   PetscOptionsHasName(((PetscObject)vec)->prefix,"-vec_view_stash",&flg);
162:   if (flg) {
163:     PetscViewer viewer;
164:     PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
165:     VecStashView(vec,viewer);
166:   }

169:   if (vec->ops->assemblybegin) {
170:     (*vec->ops->assemblybegin)(vec);
171:   }
173:   PetscObjectStateIncrease((PetscObject)vec);
174:   return(0);
175: }

179: /*
180:   Processes command line options to determine if/how a matrix
181:   is to be viewed. Called by VecAssemblyEnd().

183: .seealso: MatView_Private()

185: */
186: PetscErrorCode  VecView_Private(Vec vec)
187: {
189:   PetscTruth     flg;

192:   PetscOptionsBegin(((PetscObject)vec)->comm,((PetscObject)vec)->prefix,"Vector Options","Vec");
193:     PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
194:     if (flg) {
195:       PetscViewer viewer;
196:       PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
197:       VecView(vec,viewer);
198:     }
199:     PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
200:     if (flg) {
201:       PetscViewer viewer;
202:       PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
203:       PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);
204:       VecView(vec,viewer);
205:       PetscViewerPopFormat(viewer);
206:     }
207: #if defined(PETSC_HAVE_MATLAB_ENGINE)
208:     PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
209:     if (flg) {
210:       VecView(vec,PETSC_VIEWER_MATLAB_(((PetscObject)vec)->comm));
211:     }
212: #endif
213: #if defined(PETSC_USE_SOCKET_VIEWER)
214:     PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
215:     if (flg) {
216:       VecView(vec,PETSC_VIEWER_SOCKET_(((PetscObject)vec)->comm));
217:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(((PetscObject)vec)->comm));
218:     }
219: #endif
220:     PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
221:     if (flg) {
222:       VecView(vec,PETSC_VIEWER_BINARY_(((PetscObject)vec)->comm));
223:       PetscViewerFlush(PETSC_VIEWER_BINARY_(((PetscObject)vec)->comm));
224:     }
225:   PetscOptionsEnd();
226:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
227:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
228:   PetscOptionsHasName(((PetscObject)vec)->prefix,"-vec_view_draw",&flg);
229:   if (flg) {
230:     VecView(vec,PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
231:     PetscViewerFlush(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
232:   }
233:   PetscOptionsHasName(((PetscObject)vec)->prefix,"-vec_view_draw_lg",&flg);
234:   if (flg) {
235:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm),PETSC_VIEWER_DRAW_LG);
236:     VecView(vec,PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
237:     PetscViewerFlush(PETSC_VIEWER_DRAW_(((PetscObject)vec)->comm));
238:   }
239:   return(0);
240: }

244: /*@
245:    VecAssemblyEnd - Completes assembling the vector.  This routine should
246:    be called after VecAssemblyBegin().

248:    Collective on Vec

250:    Input Parameter:
251: .  vec - the vector

253:    Options Database Keys:
254: +  -vec_view - Prints vector in ASCII format
255: .  -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
256: .  -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
257: .  -vec_view_draw - Activates vector viewing using drawing tools
258: .  -display <name> - Sets display name (default is host)
259: .  -draw_pause <sec> - Sets number of seconds to pause after display
260: -  -vec_view_socket - Activates vector viewing using a socket
261:  
262:    Level: beginner

264: .seealso: VecAssemblyBegin(), VecSetValues()
265: @*/
266: PetscErrorCode  VecAssemblyEnd(Vec vec)
267: {

274:   if (vec->ops->assemblyend) {
275:     (*vec->ops->assemblyend)(vec);
276:   }
278:   VecView_Private(vec);
279:   return(0);
280: }

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

287:    Collective on Vec

289:    Input Parameters:
290: .  x, y  - the vectors

292:    Output Parameter:
293: .  w - the result

295:    Level: advanced

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

300:    Concepts: vector^pointwise multiply

302: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
303: @*/
304: PetscErrorCode  VecPointwiseMax(Vec w,Vec x,Vec y)
305: {

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

320:   (*w->ops->pointwisemax)(w,x,y);
321:   PetscObjectStateIncrease((PetscObject)w);
322:   return(0);
323: }


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

331:    Collective on Vec

333:    Input Parameters:
334: .  x, y  - the vectors

336:    Output Parameter:
337: .  w - the result

339:    Level: advanced

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

344:    Concepts: vector^pointwise multiply

346: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
347: @*/
348: PetscErrorCode  VecPointwiseMin(Vec w,Vec x,Vec y)
349: {

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

364:   (*w->ops->pointwisemin)(w,x,y);
365:   PetscObjectStateIncrease((PetscObject)w);
366:   return(0);
367: }

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

374:    Collective on Vec

376:    Input Parameters:
377: .  x, y  - the vectors

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

382:    Level: advanced

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

386:    Concepts: vector^pointwise multiply

388: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
389: @*/
390: PetscErrorCode  VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
391: {

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

406:   (*w->ops->pointwisemaxabs)(w,x,y);
407:   PetscObjectStateIncrease((PetscObject)w);
408:   return(0);
409: }

413: /*@
414:    VecPointwiseDivide - Computes the componentwise division w = x/y.

416:    Collective on Vec

418:    Input Parameters:
419: .  x, y  - the vectors

421:    Output Parameter:
422: .  w - the result

424:    Level: advanced

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

428:    Concepts: vector^pointwise divide

430: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
431: @*/
432: PetscErrorCode  VecPointwiseDivide(Vec w,Vec x,Vec y)
433: {

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

448:   (*w->ops->pointwisedivide)(w,x,y);
449:   PetscObjectStateIncrease((PetscObject)w);
450:   return(0);
451: }


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

459:    Collective on Vec

461:    Input Parameters:
462: .  v - a vector to mimic

464:    Output Parameter:
465: .  newv - location to put new vector

467:    Notes:
468:    VecDuplicate() does not copy the vector, but rather allocates storage
469:    for the new vector.  Use VecCopy() to copy a vector.

471:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
472:    vectors. 

474:    Level: beginner

476: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
477: @*/
478: PetscErrorCode  VecDuplicate(Vec v,Vec *newv)
479: {

486:   (*v->ops->duplicate)(v,newv);
487:   PetscObjectStateIncrease((PetscObject)*newv);
488:   return(0);
489: }

493: /*@
494:    VecDestroy - Destroys a vector.

496:    Collective on Vec

498:    Input Parameters:
499: .  v  - the vector

501:    Level: beginner

503: .seealso: VecDuplicate(), VecDestroyVecs()
504: @*/
505: PetscErrorCode  VecDestroy(Vec v)
506: {

511:   if (--((PetscObject)v)->refct > 0) return(0);
512:   /* destroy the internal part */
513:   if (v->ops->destroy) {
514:     (*v->ops->destroy)(v);
515:   }
516:   /* destroy the external/common part */
517:   if (v->mapping) {
518:     ISLocalToGlobalMappingDestroy(v->mapping);
519:   }
520:   if (v->bmapping) {
521:     ISLocalToGlobalMappingDestroy(v->bmapping);
522:   }
523:   PetscFree(v->map.range);
524:   PetscHeaderDestroy(v);
525:   return(0);
526: }

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

533:    Collective on Vec

535:    Input Parameters:
536: +  m - the number of vectors to obtain
537: -  v - a vector to mimic

539:    Output Parameter:
540: .  V - location to put pointer to array of vectors

542:    Notes:
543:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
544:    vector.

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

551:    Level: intermediate

553: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
554: @*/
555: PetscErrorCode  VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
556: {

563:   (*v->ops->duplicatevecs)(v, m,V);
564:   return(0);
565: }

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

572:    Collective on Vec

574:    Input Parameters:
575: +  vv - pointer to array of vector pointers
576: -  m - the number of vectors previously obtained

578:    Fortran Note:
579:    The Fortran interface is slightly different from that given below.
580:    See the Fortran chapter of the users manual and 
581:    petsc/src/vec/examples for details.

583:    Level: intermediate

585: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
586: @*/
587: PetscErrorCode  VecDestroyVecs(Vec vv[],PetscInt m)
588: {

595:   (*(*vv)->ops->destroyvecs)(vv,m);
596:   return(0);
597: }

599: #undef  __FUNCT__
601: /*@
602:   VecViewFromOptions - This function visualizes the vector based upon user options.

604:   Collective on Vec

606:   Input Parameters:
607: . vec   - The vector
608: . title - The title (currently ignored)

610:   Level: intermediate

612: .keywords: Vec, view, options, database
613: .seealso: VecSetFromOptions(), VecView()
614: @*/
615: PetscErrorCode  VecViewFromOptions(Vec vec, const char *title)
616: {

620:   VecView_Private(vec);
621:   return(0);
622: }

626: /*@C
627:    VecView - Views a vector object. 

629:    Collective on Vec

631:    Input Parameters:
632: +  vec - the vector
633: -  viewer - an optional visualization context

635:    Notes:
636:    The available visualization contexts include
637: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
638: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
639:          output where only the first processor opens
640:          the file.  All other processors send their 
641:          data to the first processor to print. 

643:    You can change the format the vector is printed using the 
644:    option PetscViewerSetFormat().

646:    The user can open alternative visualization contexts with
647: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
648: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
649:          specified file; corresponding input uses VecLoad()
650: .    PetscViewerDrawOpen() - Outputs vector to an X window display
651: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

653:    The user can call PetscViewerSetFormat() to specify the output
654:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
655:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
656: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
657: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
658: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
659: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
660:          format common among all vector types

662:    Level: beginner

664:    Concepts: vector^printing
665:    Concepts: vector^saving to disk

667: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
668:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
669:           PetscRealView(), PetscScalarView(), PetscIntView()
670: @*/
671: PetscErrorCode  VecView(Vec vec,PetscViewer viewer)
672: {
673:   PetscErrorCode    ierr;
674:   PetscViewerFormat format;

679:   if (!viewer) {
680:     PetscViewerASCIIGetStdout(((PetscObject)vec)->comm,&viewer);
681:   }
684:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

686:   /*
687:      Check if default viewer has been overridden, but user request it anyways
688:   */
689:   PetscViewerGetFormat(viewer,&format);
690:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
691:     PetscViewerPopFormat(viewer);
692:     (*vec->ops->viewnative)(vec,viewer);
693:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
694:   } else {
695:     (*vec->ops->view)(vec,viewer);
696:   }
697:   return(0);
698: }

702: /*@
703:    VecGetSize - Returns the global number of elements of the vector.

705:    Not Collective

707:    Input Parameter:
708: .  x - the vector

710:    Output Parameters:
711: .  size - the global length of the vector

713:    Level: beginner

715:    Concepts: vector^local size

717: .seealso: VecGetLocalSize()
718: @*/
719: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
720: {

727:   (*x->ops->getsize)(x,size);
728:   return(0);
729: }

733: /*@
734:    VecGetLocalSize - Returns the number of elements of the vector stored 
735:    in local memory. This routine may be implementation dependent, so use 
736:    with care.

738:    Not Collective

740:    Input Parameter:
741: .  x - the vector

743:    Output Parameter:
744: .  size - the length of the local piece of the vector

746:    Level: beginner

748:    Concepts: vector^size

750: .seealso: VecGetSize()
751: @*/
752: PetscErrorCode  VecGetLocalSize(Vec x,PetscInt *size)
753: {

760:   (*x->ops->getlocalsize)(x,size);
761:   return(0);
762: }

766: /*@C
767:    VecGetOwnershipRange - Returns the range of indices owned by 
768:    this processor, assuming that the vectors are laid out with the
769:    first n1 elements on the first processor, next n2 elements on the
770:    second, etc.  For certain parallel layouts this range may not be 
771:    well defined. 

773:    Not Collective

775:    Input Parameter:
776: .  x - the vector

778:    Output Parameters:
779: +  low - the first local element, pass in PETSC_NULL if not interested
780: -  high - one more than the last local element, pass in PETSC_NULL if not interested

782:    Note:
783:    The high argument is one more than the last element stored locally.

785:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

787:    Level: beginner

789:    Concepts: ownership^of vectors
790:    Concepts: vector^ownership of elements

792: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
793: @*/
794: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
795: {
801:   if (low)  *low  = x->map.rstart;
802:   if (high) *high = x->map.rend;
803:   return(0);
804: }

808: /*@C
809:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor, 
810:    assuming that the vectors are laid out with the
811:    first n1 elements on the first processor, next n2 elements on the
812:    second, etc.  For certain parallel layouts this range may not be 
813:    well defined. 

815:    Not Collective

817:    Input Parameter:
818: .  x - the vector

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

823:    Note:
824:    The high argument is one more than the last element stored locally.

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

828:    Level: beginner

830:    Concepts: ownership^of vectors
831:    Concepts: vector^ownership of elements

833: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
834: @*/
835: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
836: {

842:   PetscMapGetGlobalRange(&x->map,ranges);
843:   return(0);
844: }

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

851:    Collective on Vec

853:    Input Parameter:
854: +  x - the vector
855: .  op - the option
856: -  flag - turn the option on or off

858:    Supported Options:
859: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
860:           entries destined to be stored on a separate processor. This can be used
861:           to eliminate the global reduction in the VecAssemblyXXXX() if you know 
862:           that you have only used VecSetValues() to set local elements
863: .     VEC_IGNORE_NEGATIVE_INDICES, which means you can pass negative indices
864:           in ix in calls to VecSetValues or VecGetValues. These rows are simply
865:           ignored.

867:    Level: intermediate

869: @*/
870: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscTruth flag)
871: {

877:   if (x->ops->setoption) {
878:     (*x->ops->setoption)(x,op,flag);
879:   }
880:   return(0);
881: }

885: /* Default routines for obtaining and releasing; */
886: /* may be used by any implementation */
887: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
888: {
890:   PetscInt       i;

895:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
896:   PetscMalloc(m*sizeof(Vec*),V);
897:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
898:   return(0);
899: }

903: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
904: {
906:   PetscInt       i;

910:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
911:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
912:   PetscFree(v);
913:   return(0);
914: }

918: /*@
919:    VecResetArray - Resets a vector to use its default memory. Call this 
920:    after the use of VecPlaceArray().

922:    Not Collective

924:    Input Parameters:
925: .  vec - the vector

927:    Level: developer

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

931: @*/
932: PetscErrorCode  VecResetArray(Vec vec)
933: {

939:   if (vec->ops->resetarray) {
940:     (*vec->ops->resetarray)(vec);
941:   } else {
942:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
943:   }
944:   PetscObjectStateIncrease((PetscObject)vec);
945:   return(0);
946: }

950: /*@C 
951:   VecLoadIntoVector - Loads a vector that has been stored in binary format
952:   with VecView().

954:   Collective on PetscViewer 

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

960:   Level: intermediate

962:   Notes:
963:   The input file must contain the full global vector, as
964:   written by the routine VecView().

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

968:   Notes for advanced users:
969:   Most users should not need to know the details of the binary storage
970:   format, since VecLoad() and VecView() completely hide these details.
971:   But for anyone who's interested, the standard binary matrix storage
972:   format is
973: .vb
974:      int    VEC_FILE_COOKIE
975:      int    number of rows
976:      PetscScalar *values of all nonzeros
977: .ve

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

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

992:    Concepts: vector^loading from file

994: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
995: @*/
996: PetscErrorCode  VecLoadIntoVector(PetscViewer viewer,Vec vec)
997: {

1004:   if (!vec->ops->loadintovector) {
1005:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
1006:   }
1007:   (*vec->ops->loadintovector)(viewer,vec);
1008:   PetscObjectStateIncrease((PetscObject)vec);
1009:   return(0);
1010: }

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

1017:    Collective on Vec

1019:    Input Parameter:
1020: .  vec - the vector 

1022:    Output Parameter:
1023: .  vec - the vector reciprocal

1025:    Level: intermediate

1027:    Concepts: vector^reciprocal

1029: @*/
1030: PetscErrorCode  VecReciprocal(Vec vec)
1031: {

1037:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1038:   if (!vec->ops->reciprocal) {
1039:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
1040:   }
1041:   (*vec->ops->reciprocal)(vec);
1042:   PetscObjectStateIncrease((PetscObject)vec);
1043:   return(0);
1044: }

1048: PetscErrorCode  VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
1049: {
1052:   /* save the native version of the viewer */
1053:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
1054:     vec->ops->viewnative = vec->ops->view;
1055:   }
1056:   (((void(**)(void))vec->ops)[(int)op]) = f;
1057:   return(0);
1058: }


1063: /*@
1064:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1065:    used during the assembly process to store values that belong to 
1066:    other processors.

1068:    Collective on Vec

1070:    Input Parameters:
1071: +  vec   - the vector
1072: .  size  - the initial size of the stash.
1073: -  bsize - the initial size of the block-stash(if used).

1075:    Options Database Keys:
1076: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1077: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1079:    Level: intermediate

1081:    Notes: 
1082:      The block-stash is used for values set with VecSetValuesBlocked() while
1083:      the stash is used for values set with VecSetValues()

1085:      Run with the option -info and look for output of the form
1086:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
1087:      to determine the appropriate value, MM, to use for size and 
1088:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
1089:      to determine the value, BMM to use for bsize

1091:    Concepts: vector^stash
1092:    Concepts: stash^vector

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

1096: @*/
1097: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1098: {

1103:   VecStashSetInitialSize_Private(&vec->stash,size);
1104:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1105:   return(0);
1106: }

1110: /*@
1111:    VecConjugate - Conjugates a vector.

1113:    Collective on Vec

1115:    Input Parameters:
1116: .  x - the vector

1118:    Level: intermediate

1120:    Concepts: vector^conjugate

1122: @*/
1123: PetscErrorCode  VecConjugate(Vec x)
1124: {
1125: #ifdef PETSC_USE_COMPLEX

1131:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1132:   (*x->ops->conjugate)(x);
1133:   /* we need to copy norms here */
1134:   PetscObjectStateIncrease((PetscObject)x);
1135:   return(0);
1136: #else
1137:   return(0);
1138: #endif
1139: }

1143: /*@
1144:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1146:    Collective on Vec

1148:    Input Parameters:
1149: .  x, y  - the vectors

1151:    Output Parameter:
1152: .  w - the result

1154:    Level: advanced

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

1158:    Concepts: vector^pointwise multiply

1160: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1161: @*/
1162: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
1163: {

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

1179:   (*w->ops->pointwisemult)(w,x,y);
1181:   PetscObjectStateIncrease((PetscObject)w);
1182:   return(0);
1183: }

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

1190:    Collective on Vec

1192:    Input Parameters:
1193: +  x  - the vector
1194: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1195:           it will create one internally.

1197:    Output Parameter:
1198: .  x  - the vector

1200:    Example of Usage:
1201: .vb
1202:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1203:      VecSetRandom(x,rctx);
1204:      PetscRandomDestroy(rctx);
1205: .ve

1207:    Level: intermediate

1209:    Concepts: vector^setting to random
1210:    Concepts: random^vector

1212: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1213: @*/
1214: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
1215: {
1217:   PetscRandom    randObj = PETSC_NULL;

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

1225:   if (!rctx) {
1226:     MPI_Comm    comm;
1227:     PetscObjectGetComm((PetscObject)x,&comm);
1228:     PetscRandomCreate(comm,&randObj);
1229:     PetscRandomSetFromOptions(randObj);
1230:     rctx = randObj;
1231:   }

1234:   (*x->ops->setrandom)(x,rctx);
1236: 
1237:   if (randObj) {
1238:     PetscRandomDestroy(randObj);
1239:   }
1240:   PetscObjectStateIncrease((PetscObject)x);
1241:   return(0);
1242: }

1244: /*@
1245:   VecZeroEntries - puts a 0.0 in each element of a vector

1247:   Collective on Vec

1249:   Input Parameter:
1250: . vec - The vector

1252:   Level: beginner

1254: .keywords: Vec, set, options, database
1255: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1256: @*/
1257: PetscErrorCode  VecZeroEntries (Vec vec)
1258: {
1261:   VecSet(vec,0);
1262:   return(0);
1263: }

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

1271:   Collective on Vec

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

1276:   Level: intermediate

1278: .keywords: Vec, set, options, database, type
1279: .seealso: VecSetFromOptions(), VecSetType()
1280: */
1281: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
1282: {
1283:   PetscTruth     opt;
1284:   const char     *defaultType;
1285:   char           typeName[256];
1286:   PetscMPIInt    size;

1290:   if (((PetscObject)vec)->type_name) {
1291:     defaultType = ((PetscObject)vec)->type_name;
1292:   } else {
1293:     MPI_Comm_size(((PetscObject)vec)->comm, &size);
1294:     if (size > 1) {
1295:       defaultType = VECMPI;
1296:     } else {
1297:       defaultType = VECSEQ;
1298:     }
1299:   }

1301:   if (!VecRegisterAllCalled) {
1302:     VecRegisterAll(PETSC_NULL);
1303:   }
1304:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
1305:   if (opt) {
1306:     VecSetType(vec, typeName);
1307:   } else {
1308:     VecSetType(vec, defaultType);
1309:   }
1310:   return(0);
1311: }

1315: /*@
1316:   VecSetFromOptions - Configures the vector from the options database.

1318:   Collective on Vec

1320:   Input Parameter:
1321: . vec - The vector

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

1326:   Level: beginner

1328:   Concepts: vectors^setting options
1329:   Concepts: vectors^setting type

1331: .keywords: Vec, set, options, database
1332: .seealso: VecCreate(), VecSetOptionsPrefix()
1333: @*/
1334: PetscErrorCode  VecSetFromOptions(Vec vec)
1335: {


1341:   PetscOptionsBegin(((PetscObject)vec)->comm, ((PetscObject)vec)->prefix, "Vector options", "Vec");
1342:     /* Handle vector type options */
1343:     VecSetTypeFromOptions_Private(vec);

1345:     /* Handle specific vector options */
1346:     if (vec->ops->setfromoptions) {
1347:       (*vec->ops->setfromoptions)(vec);
1348:     }
1349:   PetscOptionsEnd();

1351:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1352:   return(0);
1353: }

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

1360:   Collective on Vec

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

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

1371:   Level: intermediate

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

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

1392:    Collective on Vec

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

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

1401:    Level: advanced

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

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

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

1428:    Collective on Vec

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

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

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

1439:    Level: advanced

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

1443:    Concepts: vector^block size
1444:    Concepts: block^vector

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

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

1461:    Not Collective

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

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

1470:    Level: developer

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

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

1489:    Collective on Vec

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

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

1499:    Level: advanced

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

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

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

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

1521:    Collective on Vec

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

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

1531:    Level: advanced

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

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

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

1553:    Not Collective

1555:    Input Parameter:
1556: .  v - the Vec context

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

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

1564:    Level: advanced

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

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

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

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

1585:    Collective on Vec

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

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

1594:    Level: advanced

1596: .keywords: Vec, setup

1598: .seealso: VecCreate(), VecDestroy()
1599: @*/
1600: PetscErrorCode  VecSetUp(Vec v)
1601: {
1602:   PetscMPIInt    size;

1607:   if (!((PetscObject)v)->type_name) {
1608:     MPI_Comm_size(((PetscObject)v)->comm, &size);
1609:     if (size == 1) {
1610:       VecSetType(v, VECSEQ);
1611:     } else {
1612:       VecSetType(v, VECMPI);
1613:     }
1614:   }
1615:   return(0);
1616: }

1618: /*  
1619:     These currently expose the PetscScalar/PetscReal in updating the
1620:     cached norm. If we push those down into the implementation these
1621:     will become independent of PetscScalar/PetscReal
1622: */

1626: /*@
1627:    VecCopy - Copies a vector. 

1629:    Collective on Vec

1631:    Input Parameter:
1632: .  x - the vector

1634:    Output Parameter:
1635: .  y - the copy

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

1641:    Level: beginner

1643: .seealso: VecDuplicate()
1644: @*/
1645: PetscErrorCode  VecCopy(Vec x,Vec y)
1646: {
1647:   PetscTruth     flgs[4];
1648:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
1650:   PetscInt       i;

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

1663:   (*x->ops->copy)(x,y);


1666:   /*
1667:    * Update cached data
1668:   */
1669:   /* in general we consider this object touched */
1670:   PetscObjectStateIncrease((PetscObject)y);

1672:   for (i=0; i<4; i++) {
1673:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
1674:   }
1675:   for (i=0; i<4; i++) {
1676:     if (flgs[i]) {
1677:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
1678:     }
1679:   }

1682:   return(0);
1683: }

1687: /*@
1688:    VecSwap - Swaps the vectors x and y.

1690:    Collective on Vec

1692:    Input Parameters:
1693: .  x, y  - the vectors

1695:    Level: advanced

1697:    Concepts: vector^swapping values

1699: @*/
1700: PetscErrorCode  VecSwap(Vec x,Vec y)
1701: {
1702:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
1703:   PetscTruth     flgxs[4],flgys[4];
1705:   PetscInt       i;

1713:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1714:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1715:   if (x->map.N != y->map.N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1716:   if (x->map.n != y->map.n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1719:   (*x->ops->swap)(x,y);

1721:   /* See if we have cached norms */
1722:   for (i=0; i<4; i++) {
1723:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
1724:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
1725:   }
1726:   for (i=0; i<4; i++) {
1727:     if (flgxs[i]) {
1728:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
1729:     }
1730:     if (flgys[i]) {
1731:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
1732:     }
1733:   }
1735:   return(0);
1736: }

1740: /*@
1741:    VecStashView - Prints the entries in the vector stash and block stash.

1743:    Collective on Vec

1745:    Input Parameters:
1746: +  v - the vector
1747: -  viewer - the viewer

1749:    Level: advanced

1751:    Concepts: vector^stash
1752:    Concepts: stash^vector

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

1756: @*/
1757: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
1758: {
1760:   PetscMPIInt    rank;
1761:   PetscInt       i,j;
1762:   PetscTruth     match;
1763:   VecStash       *s;
1764:   PetscScalar    val;


1771:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
1772:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
1773:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
1774:   MPI_Comm_rank(((PetscObject)v)->comm,&rank);
1775:   s = &v->bstash;

1777:   /* print block stash */
1778:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
1779:   for (i=0; i<s->n; i++) {
1780:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
1781:     for (j=0; j<s->bs; j++) {
1782:       val = s->array[i*s->bs+j];
1783: #if defined(PETSC_USE_COMPLEX)
1784:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
1785: #else
1786:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
1787: #endif
1788:     }
1789:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
1790:   }
1791:   PetscViewerFlush(viewer);

1793:   s = &v->stash;

1795:   /* print basic stash */
1796:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
1797:   for (i=0; i<s->n; i++) {
1798:     val = s->array[i];
1799: #if defined(PETSC_USE_COMPLEX)
1800:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
1801: #else
1802:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
1803: #endif
1804:   }
1805:   PetscViewerFlush(viewer);

1807:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1808:   return(0);
1809: }