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:    See the manual page for VecLoad() on the exact format the binary viewer stores
663:    the values in the file.

665:    Level: beginner

667:    Concepts: vector^printing
668:    Concepts: vector^saving to disk

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

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

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

707: /*@
708:    VecGetSize - Returns the global number of elements of the vector.

710:    Not Collective

712:    Input Parameter:
713: .  x - the vector

715:    Output Parameters:
716: .  size - the global length of the vector

718:    Level: beginner

720:    Concepts: vector^local size

722: .seealso: VecGetLocalSize()
723: @*/
724: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
725: {

732:   (*x->ops->getsize)(x,size);
733:   return(0);
734: }

738: /*@
739:    VecGetLocalSize - Returns the number of elements of the vector stored 
740:    in local memory. This routine may be implementation dependent, so use 
741:    with care.

743:    Not Collective

745:    Input Parameter:
746: .  x - the vector

748:    Output Parameter:
749: .  size - the length of the local piece of the vector

751:    Level: beginner

753:    Concepts: vector^size

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

765:   (*x->ops->getlocalsize)(x,size);
766:   return(0);
767: }

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

778:    Not Collective

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

783:    Output Parameters:
784: +  low - the first local element, pass in PETSC_NULL if not interested
785: -  high - one more than the last local element, pass in PETSC_NULL if not interested

787:    Note:
788:    The high argument is one more than the last element stored locally.

790:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

792:    Level: beginner

794:    Concepts: ownership^of vectors
795:    Concepts: vector^ownership of elements

797: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
798: @*/
799: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
800: {
806:   if (low)  *low  = x->map->rstart;
807:   if (high) *high = x->map->rend;
808:   return(0);
809: }

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

820:    Not Collective

822:    Input Parameter:
823: .  x - the vector

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

828:    Note:
829:    The high argument is one more than the last element stored locally.

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

833:    Level: beginner

835:    Concepts: ownership^of vectors
836:    Concepts: vector^ownership of elements

838: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
839: @*/
840: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
841: {

847:   PetscMapGetRanges(x->map,ranges);
848:   return(0);
849: }

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

856:    Collective on Vec

858:    Input Parameter:
859: +  x - the vector
860: .  op - the option
861: -  flag - turn the option on or off

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

872:    Level: intermediate

874: @*/
875: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscTruth flag)
876: {

882:   if (x->ops->setoption) {
883:     (*x->ops->setoption)(x,op,flag);
884:   }
885:   return(0);
886: }

890: /* Default routines for obtaining and releasing; */
891: /* may be used by any implementation */
892: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
893: {
895:   PetscInt       i;

900:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
901:   PetscMalloc(m*sizeof(Vec*),V);
902:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
903:   return(0);
904: }

908: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
909: {
911:   PetscInt       i;

915:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
916:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
917:   PetscFree(v);
918:   return(0);
919: }

923: /*@
924:    VecResetArray - Resets a vector to use its default memory. Call this 
925:    after the use of VecPlaceArray().

927:    Not Collective

929:    Input Parameters:
930: .  vec - the vector

932:    Level: developer

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

936: @*/
937: PetscErrorCode  VecResetArray(Vec vec)
938: {

944:   if (vec->ops->resetarray) {
945:     (*vec->ops->resetarray)(vec);
946:   } else {
947:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
948:   }
949:   PetscObjectStateIncrease((PetscObject)vec);
950:   return(0);
951: }

955: /*@C 
956:   VecLoadIntoVector - Loads a vector that has been stored in binary format
957:   with VecView().

959:   Collective on PetscViewer 

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

965:   Level: intermediate

967:   Notes:
968:   The input file must contain the full global vector, as
969:   written by the routine VecView().

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

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

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

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

997:    Concepts: vector^loading from file

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

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

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

1035:    Collective on Vec

1037:    Input Parameter:
1038: .  vec - the vector 

1040:    Output Parameter:
1041: .  vec - the vector reciprocal

1043:    Level: intermediate

1045:    Concepts: vector^reciprocal

1047: @*/
1048: PetscErrorCode  VecReciprocal(Vec vec)
1049: {

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

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


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

1088:    Collective on Vec

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

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

1099:    Level: intermediate

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

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

1111:    Concepts: vector^stash
1112:    Concepts: stash^vector

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

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

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

1130: /*@
1131:    VecConjugate - Conjugates a vector.

1133:    Collective on Vec

1135:    Input Parameters:
1136: .  x - the vector

1138:    Level: intermediate

1140:    Concepts: vector^conjugate

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

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

1163: /*@
1164:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1166:    Collective on Vec

1168:    Input Parameters:
1169: .  x, y  - the vectors

1171:    Output Parameter:
1172: .  w - the result

1174:    Level: advanced

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

1178:    Concepts: vector^pointwise multiply

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

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

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

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

1210:    Collective on Vec

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

1217:    Output Parameter:
1218: .  x  - the vector

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

1227:    Level: intermediate

1229:    Concepts: vector^setting to random
1230:    Concepts: random^vector

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

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

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

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

1264: /*@
1265:   VecZeroEntries - puts a 0.0 in each element of a vector

1267:   Collective on Vec

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

1272:   Level: beginner

1274: .keywords: Vec, set, options, database
1275: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1276: @*/
1277: PetscErrorCode  VecZeroEntries (Vec vec)
1278: {
1281:   VecSet(vec,0);
1282:   return(0);
1283: }

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

1291:   Collective on Vec

1293:   Input Parameter:
1294: . vec - The vector

1296:   Level: intermediate

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

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

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

1333: /*@
1334:   VecSetFromOptions - Configures the vector from the options database.

1336:   Collective on Vec

1338:   Input Parameter:
1339: . vec - The vector

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

1344:   Level: beginner

1346:   Concepts: vectors^setting options
1347:   Concepts: vectors^setting type

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


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

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

1369:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1370:   return(0);
1371: }

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

1378:   Collective on Vec

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

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

1389:   Level: intermediate

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

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

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

1416:    Collective on Vec

1418:    Input Parameter:
1419: +  v - the vector
1420: -  bs - the blocksize

1422:    Notes:
1423:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1425:    Level: advanced

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

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

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

1452:    Collective on Vec

1454:    Input Parameter:
1455: .  v - the vector

1457:    Output Parameter:
1458: .  bs - the blocksize

1460:    Notes:
1461:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1463:    Level: advanced

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

1467:    Concepts: vector^block size
1468:    Concepts: block^vector

1470: @*/
1471: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1472: {
1476:   *bs = v->map->bs;
1477:   return(0);
1478: }

1482: /*@
1483:    VecValid - Checks whether a vector object is valid.

1485:    Not Collective

1487:    Input Parameter:
1488: .  v - the object to check

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

1494:    Level: developer

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

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

1513:    Collective on Vec

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

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

1523:    Level: advanced

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

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

1535:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1536:   return(0);
1537: }

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

1545:    Collective on Vec

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

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

1555:    Level: advanced

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

1559: .seealso: VecGetOptionsPrefix()
1560: @*/
1561: PetscErrorCode  VecAppendOptionsPrefix(Vec v,const char prefix[])
1562: {
1564: 
1567:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1568:   return(0);
1569: }

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

1577:    Not Collective

1579:    Input Parameter:
1580: .  v - the Vec context

1582:    Output Parameter:
1583: .  prefix - pointer to the prefix string used

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

1588:    Level: advanced

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

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

1600:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1601:   return(0);
1602: }

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

1609:    Collective on Vec

1611:    Input Parameters:
1612: .  v - the Vec context

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

1618:    Level: advanced

1620: .keywords: Vec, setup

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

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

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

1650: /*@
1651:    VecCopy - Copies a vector. y <- x

1653:    Collective on Vec

1655:    Input Parameter:
1656: .  x - the vector

1658:    Output Parameter:
1659: .  y - the copy

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

1665:    Level: beginner

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

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

1686:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1687:   (*x->ops->copy)(x,y);


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

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

1705:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1706:   return(0);
1707: }

1711: /*@
1712:    VecSwap - Swaps the vectors x and y.

1714:    Collective on Vec

1716:    Input Parameters:
1717: .  x, y  - the vectors

1719:    Level: advanced

1721:    Concepts: vector^swapping values

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

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

1742:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1743:   (*x->ops->swap)(x,y);

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

1764: /*@
1765:    VecStashView - Prints the entries in the vector stash and block stash.

1767:    Collective on Vec

1769:    Input Parameters:
1770: +  v - the vector
1771: -  viewer - the viewer

1773:    Level: advanced

1775:    Concepts: vector^stash
1776:    Concepts: stash^vector

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

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


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

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

1817:   s = &v->stash;

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

1831:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1832:   return(0);
1833: }