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;
 11: PetscLogEvent  VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot;
 12: PetscLogEvent  VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY;
 13: PetscLogEvent  VEC_MTDot, VEC_NormBarrier, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin, VEC_ScatterBegin, VEC_ScatterEnd;
 14: PetscLogEvent  VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier;
 15: PetscLogEvent  VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication,VEC_Ops;
 16: PetscLogEvent  VEC_DotNormBarrier, VEC_DotNorm, VEC_AXPBYPCZ;

 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:   }

168:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
169:   if (vec->ops->assemblybegin) {
170:     (*vec->ops->assemblybegin)(vec);
171:   }
172:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
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: {

272:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
274:   if (vec->ops->assemblyend) {
275:     (*vec->ops->assemblyend)(vec);
276:   }
277:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
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:   PetscMapDestroy(v->map);
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/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_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:    Notes for HDF5 Viewer: the name of the Vec (given with PetscObjectSetName() is the name that is used
663:    for the object in the HDF5 file. If you wish to store the same vector to the HDF5 viewer (with different values,
664:    obviously) several times, you must change its name each time before calling the VecView(). The name you use
665:    here should equal the name that you use in the Vec object that you use with VecLoadIntoVector().

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

670:    Level: beginner

672:    Concepts: vector^printing
673:    Concepts: vector^saving to disk

675: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
676:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
677:           PetscRealView(), PetscScalarView(), PetscIntView()
678: @*/
679: PetscErrorCode  VecView(Vec vec,PetscViewer viewer)
680: {
681:   PetscErrorCode    ierr;
682:   PetscViewerFormat format;

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

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

712: /*@
713:    VecGetSize - Returns the global number of elements of the vector.

715:    Not Collective

717:    Input Parameter:
718: .  x - the vector

720:    Output Parameters:
721: .  size - the global length of the vector

723:    Level: beginner

725:    Concepts: vector^local size

727: .seealso: VecGetLocalSize()
728: @*/
729: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
730: {

737:   (*x->ops->getsize)(x,size);
738:   return(0);
739: }

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

748:    Not Collective

750:    Input Parameter:
751: .  x - the vector

753:    Output Parameter:
754: .  size - the length of the local piece of the vector

756:    Level: beginner

758:    Concepts: vector^size

760: .seealso: VecGetSize()
761: @*/
762: PetscErrorCode  VecGetLocalSize(Vec x,PetscInt *size)
763: {

770:   (*x->ops->getlocalsize)(x,size);
771:   return(0);
772: }

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

783:    Not Collective

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

788:    Output Parameters:
789: +  low - the first local element, pass in PETSC_NULL if not interested
790: -  high - one more than the last local element, pass in PETSC_NULL if not interested

792:    Note:
793:    The high argument is one more than the last element stored locally.

795:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

797:    Level: beginner

799:    Concepts: ownership^of vectors
800:    Concepts: vector^ownership of elements

802: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
803: @*/
804: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
805: {
811:   if (low)  *low  = x->map->rstart;
812:   if (high) *high = x->map->rend;
813:   return(0);
814: }

818: /*@C
819:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor, 
820:    assuming that the vectors are laid out with the
821:    first n1 elements on the first processor, next n2 elements on the
822:    second, etc.  For certain parallel layouts this range may not be 
823:    well defined. 

825:    Not Collective

827:    Input Parameter:
828: .  x - the vector

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

833:    Note:
834:    The high argument is one more than the last element stored locally.

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

838:    Level: beginner

840:    Concepts: ownership^of vectors
841:    Concepts: vector^ownership of elements

843: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
844: @*/
845: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
846: {

852:   PetscMapGetRanges(x->map,ranges);
853:   return(0);
854: }

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

861:    Collective on Vec

863:    Input Parameter:
864: +  x - the vector
865: .  op - the option
866: -  flag - turn the option on or off

868:    Supported Options:
869: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
870:           entries destined to be stored on a separate processor. This can be used
871:           to eliminate the global reduction in the VecAssemblyXXXX() if you know 
872:           that you have only used VecSetValues() to set local elements
873: .     VEC_IGNORE_NEGATIVE_INDICES, which means you can pass negative indices
874:           in ix in calls to VecSetValues or VecGetValues. These rows are simply
875:           ignored.

877:    Level: intermediate

879: @*/
880: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscTruth flag)
881: {

887:   if (x->ops->setoption) {
888:     (*x->ops->setoption)(x,op,flag);
889:   }
890:   return(0);
891: }

895: /* Default routines for obtaining and releasing; */
896: /* may be used by any implementation */
897: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
898: {
900:   PetscInt       i;

905:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
906:   PetscMalloc(m*sizeof(Vec*),V);
907:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
908:   return(0);
909: }

913: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
914: {
916:   PetscInt       i;

920:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
921:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
922:   PetscFree(v);
923:   return(0);
924: }

928: /*@
929:    VecResetArray - Resets a vector to use its default memory. Call this 
930:    after the use of VecPlaceArray().

932:    Not Collective

934:    Input Parameters:
935: .  vec - the vector

937:    Level: developer

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

941: @*/
942: PetscErrorCode  VecResetArray(Vec vec)
943: {

949:   if (vec->ops->resetarray) {
950:     (*vec->ops->resetarray)(vec);
951:   } else {
952:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
953:   }
954:   PetscObjectStateIncrease((PetscObject)vec);
955:   return(0);
956: }

960: /*@C 
961:   VecLoadIntoVector - Loads a vector that has been stored in binary (or HDF5) format 
962:   with VecView().

964:   Collective on PetscViewer 

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

970:   Level: intermediate

972:   Notes:
973:   The input file must contain the full global vector, as
974:   written by the routine VecView().

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

978:   If using HDF5, you must assign the Vec the same name as was used in the Vec that was stored
979:   in the file using PetscObjectSetName(). Otherwise you will get the error message:
980:   "Cannot H5Dopen2() with Vec named NAMEOFOBJECT"

982:   Notes for advanced users:
983:   Most users should not need to know the details of the binary storage
984:   format, since VecLoad() and VecView() completely hide these details.
985:   But for anyone who's interested, the standard binary matrix storage
986:   format is
987: .vb
988:      int    VEC_FILE_COOKIE
989:      int    number of rows
990:      PetscScalar *values of all nonzeros
991: .ve

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

999:    Concepts: vector^loading from file

1001: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
1002: @*/
1003: PetscErrorCode  VecLoadIntoVector(PetscViewer viewer,Vec vec)
1004: {
1005:   PetscErrorCode    ierr;
1006:   PetscViewerFormat format;

1012:   if (!vec->ops->loadintovector) {
1013:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
1014:   }
1015:   PetscLogEventBegin(VEC_Load,viewer,0,0,0);
1016:   /*
1017:      Check if default loader has been overridden, but user request it anyways
1018:   */
1019:   PetscViewerGetFormat(viewer,&format);
1020:   if (vec->ops->loadintovectornative && format == PETSC_VIEWER_NATIVE) {
1021:     PetscViewerPopFormat(viewer);
1022:     (*vec->ops->loadintovectornative)(viewer,vec);
1023:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
1024:   } else {
1025:     (*vec->ops->loadintovector)(viewer,vec);
1026:   }
1027:   PetscLogEventEnd(VEC_Load,viewer,0,0,0);
1028:   PetscObjectStateIncrease((PetscObject)vec);
1029:   return(0);
1030: }

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

1037:    Collective on Vec

1039:    Input Parameter:
1040: .  vec - the vector 

1042:    Output Parameter:
1043: .  vec - the vector reciprocal

1045:    Level: intermediate

1047:    Concepts: vector^reciprocal

1049: @*/
1050: PetscErrorCode  VecReciprocal(Vec vec)
1051: {

1057:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1058:   if (!vec->ops->reciprocal) {
1059:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
1060:   }
1061:   (*vec->ops->reciprocal)(vec);
1062:   PetscObjectStateIncrease((PetscObject)vec);
1063:   return(0);
1064: }

1068: PetscErrorCode  VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
1069: {
1072:   /* save the native version of the viewer */
1073:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
1074:     vec->ops->viewnative = vec->ops->view;
1075:   } else if (op == VECOP_LOADINTOVECTOR && !vec->ops->loadintovectornative) {
1076:     vec->ops->loadintovectornative = vec->ops->loadintovector;
1077:   }
1078:   (((void(**)(void))vec->ops)[(int)op]) = f;
1079:   return(0);
1080: }


1085: /*@
1086:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1087:    used during the assembly process to store values that belong to 
1088:    other processors.

1090:    Collective on Vec

1092:    Input Parameters:
1093: +  vec   - the vector
1094: .  size  - the initial size of the stash.
1095: -  bsize - the initial size of the block-stash(if used).

1097:    Options Database Keys:
1098: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1099: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1101:    Level: intermediate

1103:    Notes: 
1104:      The block-stash is used for values set with VecSetValuesBlocked() while
1105:      the stash is used for values set with VecSetValues()

1107:      Run with the option -info and look for output of the form
1108:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
1109:      to determine the appropriate value, MM, to use for size and 
1110:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
1111:      to determine the value, BMM to use for bsize

1113:    Concepts: vector^stash
1114:    Concepts: stash^vector

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

1118: @*/
1119: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1120: {

1125:   VecStashSetInitialSize_Private(&vec->stash,size);
1126:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1127:   return(0);
1128: }

1132: /*@
1133:    VecConjugate - Conjugates a vector.

1135:    Collective on Vec

1137:    Input Parameters:
1138: .  x - the vector

1140:    Level: intermediate

1142:    Concepts: vector^conjugate

1144: @*/
1145: PetscErrorCode  VecConjugate(Vec x)
1146: {
1147: #ifdef PETSC_USE_COMPLEX

1153:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1154:   (*x->ops->conjugate)(x);
1155:   /* we need to copy norms here */
1156:   PetscObjectStateIncrease((PetscObject)x);
1157:   return(0);
1158: #else
1159:   return(0);
1160: #endif
1161: }

1165: /*@
1166:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1168:    Collective on Vec

1170:    Input Parameters:
1171: .  x, y  - the vectors

1173:    Output Parameter:
1174: .  w - the result

1176:    Level: advanced

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

1180:    Concepts: vector^pointwise multiply

1182: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1183: @*/
1184: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
1185: {

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

1200:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1201:   (*w->ops->pointwisemult)(w,x,y);
1202:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1203:   PetscObjectStateIncrease((PetscObject)w);
1204:   return(0);
1205: }

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

1212:    Collective on Vec

1214:    Input Parameters:
1215: +  x  - the vector
1216: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1217:           it will create one internally.

1219:    Output Parameter:
1220: .  x  - the vector

1222:    Example of Usage:
1223: .vb
1224:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1225:      VecSetRandom(x,rctx);
1226:      PetscRandomDestroy(rctx);
1227: .ve

1229:    Level: intermediate

1231:    Concepts: vector^setting to random
1232:    Concepts: random^vector

1234: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1235: @*/
1236: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
1237: {
1239:   PetscRandom    randObj = PETSC_NULL;

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

1247:   if (!rctx) {
1248:     MPI_Comm    comm;
1249:     PetscObjectGetComm((PetscObject)x,&comm);
1250:     PetscRandomCreate(comm,&randObj);
1251:     PetscRandomSetFromOptions(randObj);
1252:     rctx = randObj;
1253:   }

1255:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1256:   (*x->ops->setrandom)(x,rctx);
1257:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
1258: 
1259:   if (randObj) {
1260:     PetscRandomDestroy(randObj);
1261:   }
1262:   PetscObjectStateIncrease((PetscObject)x);
1263:   return(0);
1264: }

1266: /*@
1267:   VecZeroEntries - puts a 0.0 in each element of a vector

1269:   Collective on Vec

1271:   Input Parameter:
1272: . vec - The vector

1274:   Level: beginner

1276: .keywords: Vec, set, options, database
1277: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1278: @*/
1279: PetscErrorCode  VecZeroEntries (Vec vec)
1280: {
1283:   VecSet(vec,0);
1284:   return(0);
1285: }

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

1293:   Collective on Vec

1295:   Input Parameter:
1296: . vec - The vector

1298:   Level: intermediate

1300: .keywords: Vec, set, options, database, type
1301: .seealso: VecSetFromOptions(), VecSetType()
1302: */
1303: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
1304: {
1305:   PetscTruth     opt;
1306:   const VecType  defaultType;
1307:   char           typeName[256];
1308:   PetscMPIInt    size;

1312:   if (((PetscObject)vec)->type_name) {
1313:     defaultType = ((PetscObject)vec)->type_name;
1314:   } else {
1315:     MPI_Comm_size(((PetscObject)vec)->comm, &size);
1316:     if (size > 1) {
1317:       defaultType = VECMPI;
1318:     } else {
1319:       defaultType = VECSEQ;
1320:     }
1321:   }

1323:   if (!VecRegisterAllCalled) {VecRegisterAll(PETSC_NULL);}
1324:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
1325:   if (opt) {
1326:     VecSetType(vec, typeName);
1327:   } else {
1328:     VecSetType(vec, defaultType);
1329:   }
1330:   return(0);
1331: }

1335: /*@
1336:   VecSetFromOptions - Configures the vector from the options database.

1338:   Collective on Vec

1340:   Input Parameter:
1341: . vec - The vector

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

1346:   Level: beginner

1348:   Concepts: vectors^setting options
1349:   Concepts: vectors^setting type

1351: .keywords: Vec, set, options, database
1352: .seealso: VecCreate(), VecSetOptionsPrefix()
1353: @*/
1354: PetscErrorCode  VecSetFromOptions(Vec vec)
1355: {


1361:   PetscOptionsBegin(((PetscObject)vec)->comm, ((PetscObject)vec)->prefix, "Vector options", "Vec");
1362:     /* Handle vector type options */
1363:     VecSetTypeFromOptions_Private(vec);

1365:     /* Handle specific vector options */
1366:     if (vec->ops->setfromoptions) {
1367:       (*vec->ops->setfromoptions)(vec);
1368:     }
1369:   PetscOptionsEnd();

1371:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1372:   return(0);
1373: }

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

1380:   Collective on Vec

1382:   Input Parameters:
1383: + v - the vector
1384: . n - the local size (or PETSC_DECIDE to have it set)
1385: - N - the global size (or PETSC_DECIDE)

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

1391:   Level: intermediate

1393: .seealso: VecGetSize(), PetscSplitOwnership()
1394: @*/
1395: PetscErrorCode  VecSetSizes(Vec v, PetscInt n, PetscInt N)
1396: {

1401:   if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
1402:   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);
1403:   v->map->n = n;
1404:   v->map->N = N;
1405:   if (v->ops->create) {
1406:     (*v->ops->create)(v);
1407:     v->ops->create = 0;
1408:   }
1409:   return(0);
1410: }

1414: /*@
1415:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
1416:    and VecSetValuesBlockedLocal().

1418:    Collective on Vec

1420:    Input Parameter:
1421: +  v - the vector
1422: -  bs - the blocksize

1424:    Notes:
1425:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1427:    Level: advanced

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

1431:   Concepts: block size^vectors
1432: @*/
1433: PetscErrorCode  VecSetBlockSize(Vec v,PetscInt bs)
1434: {
1437:   if (bs <= 0) bs = 1;
1438:   if (bs == v->map->bs) return(0);
1439:   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);
1440:   if (v->map->n != -1 && v->map->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
1441:    Try setting blocksize before setting the vector type",v->map->n,bs);
1442: 
1443:   v->map->bs   = bs;
1444:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
1445:   return(0);
1446: }

1450: /*@
1451:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
1452:    and VecSetValuesBlockedLocal().

1454:    Collective on Vec

1456:    Input Parameter:
1457: .  v - the vector

1459:    Output Parameter:
1460: .  bs - the blocksize

1462:    Notes:
1463:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1465:    Level: advanced

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

1469:    Concepts: vector^block size
1470:    Concepts: block^vector

1472: @*/
1473: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1474: {
1478:   *bs = v->map->bs;
1479:   return(0);
1480: }

1484: /*@
1485:    VecValid - Checks whether a vector object is valid.

1487:    Not Collective

1489:    Input Parameter:
1490: .  v - the object to check

1492:    Output Parameter:
1493: .  flg - flag indicating vector status, either
1494:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

1496:    Level: developer

1498: @*/
1499: PetscErrorCode  VecValid(Vec v,PetscTruth *flg)
1500: {
1503:   if (!v)                                          *flg = PETSC_FALSE;
1504:   else if (((PetscObject)v)->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
1505:   else                                             *flg = PETSC_TRUE;
1506:   return(0);
1507: }

1511: /*@C
1512:    VecSetOptionsPrefix - Sets the prefix used for searching for all 
1513:    Vec options in the database.

1515:    Collective on Vec

1517:    Input Parameter:
1518: +  v - the Vec context
1519: -  prefix - the prefix to prepend to all option names

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

1525:    Level: advanced

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

1529: .seealso: VecSetFromOptions()
1530: @*/
1531: PetscErrorCode  VecSetOptionsPrefix(Vec v,const char prefix[])
1532: {

1537:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1538:   return(0);
1539: }

1543: /*@C
1544:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all 
1545:    Vec options in the database.

1547:    Collective on Vec

1549:    Input Parameters:
1550: +  v - the Vec context
1551: -  prefix - the prefix to prepend to all option names

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

1557:    Level: advanced

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

1561: .seealso: VecGetOptionsPrefix()
1562: @*/
1563: PetscErrorCode  VecAppendOptionsPrefix(Vec v,const char prefix[])
1564: {
1566: 
1569:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1570:   return(0);
1571: }

1575: /*@C
1576:    VecGetOptionsPrefix - Sets the prefix used for searching for all 
1577:    Vec options in the database.

1579:    Not Collective

1581:    Input Parameter:
1582: .  v - the Vec context

1584:    Output Parameter:
1585: .  prefix - pointer to the prefix string used

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

1590:    Level: advanced

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

1594: .seealso: VecAppendOptionsPrefix()
1595: @*/
1596: PetscErrorCode  VecGetOptionsPrefix(Vec v,const char *prefix[])
1597: {

1602:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1603:   return(0);
1604: }

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

1611:    Collective on Vec

1613:    Input Parameters:
1614: .  v - the Vec context

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

1620:    Level: advanced

1622: .keywords: Vec, setup

1624: .seealso: VecCreate(), VecDestroy()
1625: @*/
1626: PetscErrorCode  VecSetUp(Vec v)
1627: {
1628:   PetscMPIInt    size;

1633:   if (!((PetscObject)v)->type_name) {
1634:     MPI_Comm_size(((PetscObject)v)->comm, &size);
1635:     if (size == 1) {
1636:       VecSetType(v, VECSEQ);
1637:     } else {
1638:       VecSetType(v, VECMPI);
1639:     }
1640:   }
1641:   return(0);
1642: }

1644: /*  
1645:     These currently expose the PetscScalar/PetscReal in updating the
1646:     cached norm. If we push those down into the implementation these
1647:     will become independent of PetscScalar/PetscReal
1648: */

1652: /*@
1653:    VecCopy - Copies a vector. y <- x

1655:    Collective on Vec

1657:    Input Parameter:
1658: .  x - the vector

1660:    Output Parameter:
1661: .  y - the copy

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

1667:    Level: beginner

1669: .seealso: VecDuplicate()
1670: @*/
1671: PetscErrorCode  VecCopy(Vec x,Vec y)
1672: {
1673:   PetscTruth     flgs[4];
1674:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
1676:   PetscInt       i;

1684:   if (x == y) return(0);
1685:   if (x->map->N != y->map->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1686:   if (x->map->n != y->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1688:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1689:   (*x->ops->copy)(x,y);


1692:   /*
1693:    * Update cached data
1694:   */
1695:   /* in general we consider this object touched */
1696:   PetscObjectStateIncrease((PetscObject)y);

1698:   for (i=0; i<4; i++) {
1699:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
1700:   }
1701:   for (i=0; i<4; i++) {
1702:     if (flgs[i]) {
1703:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
1704:     }
1705:   }

1707:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1708:   return(0);
1709: }

1713: /*@
1714:    VecSwap - Swaps the vectors x and y.

1716:    Collective on Vec

1718:    Input Parameters:
1719: .  x, y  - the vectors

1721:    Level: advanced

1723:    Concepts: vector^swapping values

1725: @*/
1726: PetscErrorCode  VecSwap(Vec x,Vec y)
1727: {
1728:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
1729:   PetscTruth     flgxs[4],flgys[4];
1731:   PetscInt       i;

1739:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1740:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1741:   if (x->map->N != y->map->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1742:   if (x->map->n != y->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1744:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1745:   (*x->ops->swap)(x,y);

1747:   /* See if we have cached norms */
1748:   for (i=0; i<4; i++) {
1749:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
1750:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
1751:   }
1752:   for (i=0; i<4; i++) {
1753:     if (flgxs[i]) {
1754:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
1755:     }
1756:     if (flgys[i]) {
1757:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
1758:     }
1759:   }
1760:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
1761:   return(0);
1762: }

1766: /*@
1767:    VecStashView - Prints the entries in the vector stash and block stash.

1769:    Collective on Vec

1771:    Input Parameters:
1772: +  v - the vector
1773: -  viewer - the viewer

1775:    Level: advanced

1777:    Concepts: vector^stash
1778:    Concepts: stash^vector

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

1782: @*/
1783: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
1784: {
1786:   PetscMPIInt    rank;
1787:   PetscInt       i,j;
1788:   PetscTruth     match;
1789:   VecStash       *s;
1790:   PetscScalar    val;


1797:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
1798:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
1799:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
1800:   MPI_Comm_rank(((PetscObject)v)->comm,&rank);
1801:   s = &v->bstash;

1803:   /* print block stash */
1804:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
1805:   for (i=0; i<s->n; i++) {
1806:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
1807:     for (j=0; j<s->bs; j++) {
1808:       val = s->array[i*s->bs+j];
1809: #if defined(PETSC_USE_COMPLEX)
1810:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
1811: #else
1812:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
1813: #endif
1814:     }
1815:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
1816:   }
1817:   PetscViewerFlush(viewer);

1819:   s = &v->stash;

1821:   /* print basic stash */
1822:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
1823:   for (i=0; i<s->n; i++) {
1824:     val = s->array[i];
1825: #if defined(PETSC_USE_COMPLEX)
1826:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
1827: #else
1828:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
1829: #endif
1830:   }
1831:   PetscViewerFlush(viewer);

1833:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1834:   return(0);
1835: }