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;

 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  VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
 41: {
 44:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
 45:   VecStashGetInfo_Private(&vec->bstash,bnstash,breallocs);
 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  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  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  VecAssemblyBegin(Vec vec)
150: {
152:   PetscTruth     flg;


158:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
159:   if (flg) {
160:     PetscViewer viewer;
161:     PetscViewerASCIIGetStdout(vec->comm,&viewer);
162:     VecStashView(vec,viewer);
163:   }

166:   if (vec->ops->assemblybegin) {
167:     (*vec->ops->assemblybegin)(vec);
168:   }
170:   PetscObjectStateIncrease((PetscObject)vec);
171:   return(0);
172: }

176: /*
177:   Processes command line options to determine if/how a matrix
178:   is to be viewed. Called by VecAssemblyEnd().

180: .seealso: MatView_Private()

182: */
183: PetscErrorCode  VecView_Private(Vec vec)
184: {
186:   PetscTruth     flg;

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

241: /*@
242:    VecAssemblyEnd - Completes assembling the vector.  This routine should
243:    be called after VecAssemblyBegin().

245:    Collective on Vec

247:    Input Parameter:
248: .  vec - the vector

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

261: .seealso: VecAssemblyBegin(), VecSetValues()
262: @*/
263: PetscErrorCode  VecAssemblyEnd(Vec vec)
264: {

271:   if (vec->ops->assemblyend) {
272:     (*vec->ops->assemblyend)(vec);
273:   }
275:   VecView_Private(vec);
276:   return(0);
277: }

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

284:    Collective on Vec

286:    Input Parameters:
287: .  x, y  - the vectors

289:    Output Parameter:
290: .  w - the result

292:    Level: advanced

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

297:    Concepts: vector^pointwise multiply

299: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
300: @*/
301: PetscErrorCode  VecPointwiseMax(Vec w,Vec x,Vec y)
302: {

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

317:   (*w->ops->pointwisemax)(w,x,y);
318:   PetscObjectStateIncrease((PetscObject)w);
319:   return(0);
320: }


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

328:    Collective on Vec

330:    Input Parameters:
331: .  x, y  - the vectors

333:    Output Parameter:
334: .  w - the result

336:    Level: advanced

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

341:    Concepts: vector^pointwise multiply

343: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
344: @*/
345: PetscErrorCode  VecPointwiseMin(Vec w,Vec x,Vec y)
346: {

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

361:   (*w->ops->pointwisemin)(w,x,y);
362:   PetscObjectStateIncrease((PetscObject)w);
363:   return(0);
364: }

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

371:    Collective on Vec

373:    Input Parameters:
374: .  x, y  - the vectors

376:    Output Parameter:
377: .  w - the result

379:    Level: advanced

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

383:    Concepts: vector^pointwise multiply

385: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
386: @*/
387: PetscErrorCode  VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
388: {

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

403:   (*w->ops->pointwisemaxabs)(w,x,y);
404:   PetscObjectStateIncrease((PetscObject)w);
405:   return(0);
406: }

410: /*@
411:    VecPointwiseDivide - Computes the componentwise division w = x/y.

413:    Collective on Vec

415:    Input Parameters:
416: .  x, y  - the vectors

418:    Output Parameter:
419: .  w - the result

421:    Level: advanced

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

425:    Concepts: vector^pointwise divide

427: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
428: @*/
429: PetscErrorCode  VecPointwiseDivide(Vec w,Vec x,Vec y)
430: {

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

445:   (*w->ops->pointwisedivide)(w,x,y);
446:   PetscObjectStateIncrease((PetscObject)w);
447:   return(0);
448: }


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

456:    Collective on Vec

458:    Input Parameters:
459: .  v - a vector to mimic

461:    Output Parameter:
462: .  newv - location to put new vector

464:    Notes:
465:    VecDuplicate() does not copy the vector, but rather allocates storage
466:    for the new vector.  Use VecCopy() to copy a vector.

468:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
469:    vectors. 

471:    Level: beginner

473: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
474: @*/
475: PetscErrorCode  VecDuplicate(Vec v,Vec *newv)
476: {

483:   (*v->ops->duplicate)(v,newv);
484:   PetscObjectStateIncrease((PetscObject)*newv);
485:   return(0);
486: }

490: /*@
491:    VecDestroy - Destroys a vector.

493:    Collective on Vec

495:    Input Parameters:
496: .  v  - the vector

498:    Level: beginner

500: .seealso: VecDuplicate(), VecDestroyVecs()
501: @*/
502: PetscErrorCode  VecDestroy(Vec v)
503: {

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

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

530:    Collective on Vec

532:    Input Parameters:
533: +  m - the number of vectors to obtain
534: -  v - a vector to mimic

536:    Output Parameter:
537: .  V - location to put pointer to array of vectors

539:    Notes:
540:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
541:    vector.

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

548:    Level: intermediate

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

560:   (*v->ops->duplicatevecs)(v, m,V);
561:   return(0);
562: }

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

569:    Collective on Vec

571:    Input Parameters:
572: +  vv - pointer to array of vector pointers
573: -  m - the number of vectors previously obtained

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

580:    Level: intermediate

582: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
583: @*/
584: PetscErrorCode  VecDestroyVecs(Vec vv[],PetscInt m)
585: {

592:   (*(*vv)->ops->destroyvecs)(vv,m);
593:   return(0);
594: }

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

601:   Collective on Vec

603:   Input Parameters:
604: . vec   - The vector
605: . title - The title

607:   Level: intermediate

609: .keywords: Vec, view, options, database
610: .seealso: VecSetFromOptions(), VecView()
611: @*/
612: PetscErrorCode  VecViewFromOptions(Vec vec, char *title)
613: {
614:   PetscViewer    viewer;
615:   PetscDraw      draw;
616:   PetscTruth     opt;
617:   char           *titleStr;
618:   char           typeName[1024];
619:   char           fileName[PETSC_MAX_PATH_LEN];
620:   size_t         len;

624:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
625:   if (opt) {
626:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
627:     PetscStrlen(typeName, &len);
628:     if (len > 0) {
629:       PetscViewerCreate(vec->comm, &viewer);
630:       PetscViewerSetType(viewer, typeName);
631:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
632:       if (opt) {
633:         PetscViewerFileSetName(viewer, fileName);
634:       } else {
635:         PetscViewerFileSetName(viewer, vec->name);
636:       }
637:       VecView(vec, viewer);
638:       PetscViewerFlush(viewer);
639:       PetscViewerDestroy(viewer);
640:     } else {
641:       PetscViewerASCIIGetStdout(vec->comm,&viewer);
642:       VecView(vec, viewer);
643:     }
644:   }
645:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
646:   if (opt) {
647:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
648:     PetscViewerDrawGetDraw(viewer, 0, &draw);
649:     if (title) {
650:       titleStr = title;
651:     } else {
652:       PetscObjectName((PetscObject) vec);
653:       titleStr = vec->name;
654:     }
655:     PetscDrawSetTitle(draw, titleStr);
656:     VecView(vec, viewer);
657:     PetscViewerFlush(viewer);
658:     PetscDrawPause(draw);
659:     PetscViewerDestroy(viewer);
660:   }
661:   return(0);
662: }

666: /*@C
667:    VecView - Views a vector object. 

669:    Collective on Vec

671:    Input Parameters:
672: +  vec - the vector
673: -  viewer - an optional visualization context

675:    Notes:
676:    The available visualization contexts include
677: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
678: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
679:          output where only the first processor opens
680:          the file.  All other processors send their 
681:          data to the first processor to print. 

683:    You can change the format the vector is printed using the 
684:    option PetscViewerSetFormat().

686:    The user can open alternative visualization contexts with
687: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
688: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
689:          specified file; corresponding input uses VecLoad()
690: .    PetscViewerDrawOpen() - Outputs vector to an X window display
691: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

693:    The user can call PetscViewerSetFormat() to specify the output
694:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
695:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
696: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
697: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
698: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
699: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
700:          format common among all vector types

702:    Level: beginner

704:    Concepts: vector^printing
705:    Concepts: vector^saving to disk

707: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
708:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
709:           PetscRealView(), PetscScalarView(), PetscIntView()
710: @*/
711: PetscErrorCode  VecView(Vec vec,PetscViewer viewer)
712: {
713:   PetscErrorCode    ierr;
714:   PetscViewerFormat format;

719:   if (!viewer) {
720:     PetscViewerASCIIGetStdout(vec->comm,&viewer);
721:   }
724:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

726:   /*
727:      Check if default viewer has been overridden, but user request it anyways
728:   */
729:   PetscViewerGetFormat(viewer,&format);
730:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
731:     PetscViewerPopFormat(viewer);
732:     (*vec->ops->viewnative)(vec,viewer);
733:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
734:   } else {
735:     (*vec->ops->view)(vec,viewer);
736:   }
737:   return(0);
738: }

742: /*@
743:    VecGetSize - Returns the global number of elements of the vector.

745:    Not Collective

747:    Input Parameter:
748: .  x - the vector

750:    Output Parameters:
751: .  size - the global length of the vector

753:    Level: beginner

755:    Concepts: vector^local size

757: .seealso: VecGetLocalSize()
758: @*/
759: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
760: {

767:   (*x->ops->getsize)(x,size);
768:   return(0);
769: }

773: /*@
774:    VecGetLocalSize - Returns the number of elements of the vector stored 
775:    in local memory. This routine may be implementation dependent, so use 
776:    with care.

778:    Not Collective

780:    Input Parameter:
781: .  x - the vector

783:    Output Parameter:
784: .  size - the length of the local piece of the vector

786:    Level: beginner

788:    Concepts: vector^size

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

800:   (*x->ops->getlocalsize)(x,size);
801:   return(0);
802: }

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

813:    Not Collective

815:    Input Parameter:
816: .  x - the vector

818:    Output Parameters:
819: +  low - the first local element, pass in PETSC_NULL if not interested
820: -  high - one more than the last local element, pass in PETSC_NULL if not interested

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

825:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

827:    Level: beginner

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

832: @*/
833: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
834: {
840:   if (low)  *low  = x->map.rstart;
841:   if (high) *high = x->map.rend;
842:   return(0);
843: }

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

850:    Collective on Vec

852:    Input Parameter:
853: +  x - the vector
854: -  op - the option

856:    Supported Options:
857: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
858:       entries destined to be stored on a separate processor. This can be used
859:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
860:       that you have only used VecSetValues() to set local elements
861: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

863:    Level: intermediate

865: @*/
866: PetscErrorCode  VecSetOption(Vec x,VecOption op)
867: {

873:   if (x->ops->setoption) {
874:     (*x->ops->setoption)(x,op);
875:   }
876:   return(0);
877: }

881: /* Default routines for obtaining and releasing; */
882: /* may be used by any implementation */
883: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
884: {
886:   PetscInt       i;

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

899: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
900: {
902:   PetscInt       i;

906:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
907:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
908:   PetscFree(v);
909:   return(0);
910: }

914: /*@
915:    VecResetArray - Resets a vector to use its default memory. Call this 
916:    after the use of VecPlaceArray().

918:    Not Collective

920:    Input Parameters:
921: .  vec - the vector

923:    Level: developer

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

927: @*/
928: PetscErrorCode  VecResetArray(Vec vec)
929: {

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

946: /*@C 
947:   VecLoadIntoVector - Loads a vector that has been stored in binary format
948:   with VecView().

950:   Collective on PetscViewer 

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

956:   Level: intermediate

958:   Notes:
959:   The input file must contain the full global vector, as
960:   written by the routine VecView().

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

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

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

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

988:    Concepts: vector^loading from file

990: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
991: @*/
992: PetscErrorCode  VecLoadIntoVector(PetscViewer viewer,Vec vec)
993: {

1000:   if (!vec->ops->loadintovector) {
1001:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
1002:   }
1003:   (*vec->ops->loadintovector)(viewer,vec);
1004:   PetscObjectStateIncrease((PetscObject)vec);
1005:   return(0);
1006: }

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

1013:    Collective on Vec

1015:    Input Parameter:
1016: .  vec - the vector 

1018:    Output Parameter:
1019: .  vec - the vector reciprocal

1021:    Level: intermediate

1023:    Concepts: vector^reciprocal

1025: @*/
1026: PetscErrorCode  VecReciprocal(Vec vec)
1027: {

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

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


1059: /*@
1060:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1061:    used during the assembly process to store values that belong to 
1062:    other processors.

1064:    Collective on Vec

1066:    Input Parameters:
1067: +  vec   - the vector
1068: .  size  - the initial size of the stash.
1069: -  bsize - the initial size of the block-stash(if used).

1071:    Options Database Keys:
1072: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1073: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1075:    Level: intermediate

1077:    Notes: 
1078:      The block-stash is used for values set with VecSetValuesBlocked() while
1079:      the stash is used for values set with VecSetValues()

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

1087:    Concepts: vector^stash
1088:    Concepts: stash^vector

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

1092: @*/
1093: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1094: {

1099:   VecStashSetInitialSize_Private(&vec->stash,size);
1100:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1101:   return(0);
1102: }

1106: /*@
1107:    VecConjugate - Conjugates a vector.

1109:    Collective on Vec

1111:    Input Parameters:
1112: .  x - the vector

1114:    Level: intermediate

1116:    Concepts: vector^conjugate

1118: @*/
1119: PetscErrorCode  VecConjugate(Vec x)
1120: {
1121: #ifdef PETSC_USE_COMPLEX

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

1139: /*@
1140:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1142:    Collective on Vec

1144:    Input Parameters:
1145: .  x, y  - the vectors

1147:    Output Parameter:
1148: .  w - the result

1150:    Level: advanced

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

1154:    Concepts: vector^pointwise multiply

1156: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1157: @*/
1158: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
1159: {

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

1175:   (*w->ops->pointwisemult)(w,x,y);
1177:   PetscObjectStateIncrease((PetscObject)w);
1178:   return(0);
1179: }

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

1186:    Collective on Vec

1188:    Input Parameters:
1189: +  x  - the vector
1190: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1191:           it will create one internally.

1193:    Output Parameter:
1194: .  x  - the vector

1196:    Example of Usage:
1197: .vb
1198:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1199:      VecSetRandom(x,rctx);
1200:      PetscRandomDestroy(rctx);
1201: .ve

1203:    Level: intermediate

1205:    Concepts: vector^setting to random
1206:    Concepts: random^vector

1208: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1209: @*/
1210: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
1211: {
1213:   PetscRandom    randObj = PETSC_NULL;

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

1221:   if (!rctx) {
1222:     MPI_Comm    comm;
1223:     PetscObjectGetComm((PetscObject)x,&comm);
1224:     PetscRandomCreate(comm,&randObj);
1225:     PetscRandomSetFromOptions(randObj);
1226:     rctx = randObj;
1227:   }

1230:   (*x->ops->setrandom)(x,rctx);
1232: 
1233:   if (randObj) {
1234:     PetscRandomDestroy(randObj);
1235:   }
1236:   PetscObjectStateIncrease((PetscObject)x);
1237:   return(0);
1238: }

1240: /*@
1241:   VecZeroEntries - puts a 0.0 in each element of a vector

1243:   Collective on Vec

1245:   Input Parameter:
1246: . vec - The vector

1248:   Level: beginner

1250: .keywords: Vec, set, options, database
1251: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1252: @*/
1253: PetscErrorCode  VecZeroEntries (Vec vec)
1254: {
1257:   VecSet(vec,0);
1258:   return(0);
1259: }

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

1267:   Collective on Vec

1269:   Input Parameter:
1270: . vec - The vector

1272:   Level: intermediate

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

1286:   if (vec->type_name) {
1287:     defaultType = vec->type_name;
1288:   } else {
1289:     MPI_Comm_size(vec->comm, &size);
1290:     if (size > 1) {
1291:       defaultType = VECMPI;
1292:     } else {
1293:       defaultType = VECSEQ;
1294:     }
1295:   }

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

1311: /*@
1312:   VecSetFromOptions - Configures the vector from the options database.

1314:   Collective on Vec

1316:   Input Parameter:
1317: . vec - The vector

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

1322:   Level: beginner

1324:   Concepts: vectors^setting options
1325:   Concepts: vectors^setting type

1327: .keywords: Vec, set, options, database
1328: .seealso: VecCreate(), VecSetOptionsPrefix()
1329: @*/
1330: PetscErrorCode  VecSetFromOptions(Vec vec)
1331: {


1337:   PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");
1338:     /* Handle vector type options */
1339:     VecSetTypeFromOptions_Private(vec);

1341:     /* Handle specific vector options */
1342:     if (vec->ops->setfromoptions) {
1343:       (*vec->ops->setfromoptions)(vec);
1344:     }
1345:   PetscOptionsEnd();

1347:   VecViewFromOptions(vec, vec->name);
1348:   return(0);
1349: }

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

1356:   Collective on Vec

1358:   Input Parameters:
1359: + v - the vector
1360: . n - the local size (or PETSC_DECIDE to have it set)
1361: - N - the global size (or PETSC_DECIDE)

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

1367:   Level: intermediate

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

1384: /*@
1385:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
1386:    and VecSetValuesBlockedLocal().

1388:    Collective on Vec

1390:    Input Parameter:
1391: +  v - the vector
1392: -  bs - the blocksize

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

1397:    Level: advanced

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

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

1420: /*@
1421:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
1422:    and VecSetValuesBlockedLocal().

1424:    Collective on Vec

1426:    Input Parameter:
1427: .  v - the vector

1429:    Output Parameter:
1430: .  bs - the blocksize

1432:    Notes:
1433:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1435:    Level: advanced

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

1439:    Concepts: vector^block size
1440:    Concepts: block^vector

1442: @*/
1443: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1444: {
1448:   *bs = v->map.bs;
1449:   return(0);
1450: }

1454: /*@
1455:    VecValid - Checks whether a vector object is valid.

1457:    Not Collective

1459:    Input Parameter:
1460: .  v - the object to check

1462:    Output Parameter:
1463: .  flg - flag indicating vector status, either
1464:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

1466:    Level: developer

1468: @*/
1469: PetscErrorCode  VecValid(Vec v,PetscTruth *flg)
1470: {
1473:   if (!v)                           *flg = PETSC_FALSE;
1474:   else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
1475:   else                              *flg = PETSC_TRUE;
1476:   return(0);
1477: }

1481: /*@C
1482:    VecSetOptionsPrefix - Sets the prefix used for searching for all 
1483:    Vec options in the database.

1485:    Collective on Vec

1487:    Input Parameter:
1488: +  v - the Vec context
1489: -  prefix - the prefix to prepend to all option names

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

1495:    Level: advanced

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

1499: .seealso: VecSetFromOptions()
1500: @*/
1501: PetscErrorCode  VecSetOptionsPrefix(Vec v,const char prefix[])
1502: {

1507:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1508:   return(0);
1509: }

1513: /*@C
1514:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all 
1515:    Vec options in the database.

1517:    Collective on Vec

1519:    Input Parameters:
1520: +  v - the Vec context
1521: -  prefix - the prefix to prepend to all option names

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

1527:    Level: advanced

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

1531: .seealso: VecGetOptionsPrefix()
1532: @*/
1533: PetscErrorCode  VecAppendOptionsPrefix(Vec v,const char prefix[])
1534: {
1536: 
1539:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1540:   return(0);
1541: }

1545: /*@C
1546:    VecGetOptionsPrefix - Sets the prefix used for searching for all 
1547:    Vec options in the database.

1549:    Not Collective

1551:    Input Parameter:
1552: .  v - the Vec context

1554:    Output Parameter:
1555: .  prefix - pointer to the prefix string used

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

1560:    Level: advanced

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

1564: .seealso: VecAppendOptionsPrefix()
1565: @*/
1566: PetscErrorCode  VecGetOptionsPrefix(Vec v,const char *prefix[])
1567: {

1572:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1573:   return(0);
1574: }

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

1581:    Collective on Vec

1583:    Input Parameters:
1584: .  v - the Vec context

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

1590:    Level: advanced

1592: .keywords: Vec, setup

1594: .seealso: VecCreate(), VecDestroy()
1595: @*/
1596: PetscErrorCode  VecSetUp(Vec v)
1597: {

1602:   VecSetFromOptions(v);
1603:   return(0);
1604: }

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

1614: /*@
1615:    VecCopy - Copies a vector. 

1617:    Collective on Vec

1619:    Input Parameter:
1620: .  x - the vector

1622:    Output Parameter:
1623: .  y - the copy

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

1629:    Level: beginner

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

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

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


1654:   /*
1655:    * Update cached data
1656:   */
1657:   /* in general we consider this object touched */
1658:   PetscObjectStateIncrease((PetscObject)y);

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

1670:   return(0);
1671: }

1675: /*@
1676:    VecSwap - Swaps the vectors x and y.

1678:    Collective on Vec

1680:    Input Parameters:
1681: .  x, y  - the vectors

1683:    Level: advanced

1685:    Concepts: vector^swapping values

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

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

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

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

1728: /*@
1729:    VecStashView - Prints the entries in the vector stash and block stash.

1731:    Collective on Vec

1733:    Input Parameters:
1734: +  v - the vector
1735: -  viewer - the viewer

1737:    Level: advanced

1739:    Concepts: vector^stash
1740:    Concepts: stash^vector

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

1744: @*/
1745: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
1746: {
1748:   PetscMPIInt    rank;
1749:   PetscInt       i,j;
1750:   PetscTruth     match;
1751:   VecStash       *s;
1752:   PetscScalar    val;


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

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

1781:   s = &v->stash;

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

1795:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1796:   return(0);
1797: }