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

 36:    Level: advanced

 38: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()

 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 = PETSC_FALSE;


161:   PetscOptionsGetTruth(((PetscObject)vec)->prefix,"-vec_view_stash",&flg,PETSC_NULL);
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 = PETSC_FALSE;

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

250: /*@
251:    VecAssemblyEnd - Completes assembling the vector.  This routine should
252:    be called after VecAssemblyBegin().

254:    Collective on Vec

256:    Input Parameter:
257: .  vec - the vector

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

268:    Level: beginner

270: .seealso: VecAssemblyBegin(), VecSetValues()
271: @*/
272: PetscErrorCode  VecAssemblyEnd(Vec vec)
273: {

278:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
280:   if (vec->ops->assemblyend) {
281:     (*vec->ops->assemblyend)(vec);
282:   }
283:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
284:   VecView_Private(vec);
285:   return(0);
286: }

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

293:    Collective on Vec

295:    Input Parameters:
296: .  x, y  - the vectors

298:    Output Parameter:
299: .  w - the result

301:    Level: advanced

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

306:    Concepts: vector^pointwise multiply

308: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
309: @*/
310: PetscErrorCode  VecPointwiseMax(Vec w,Vec x,Vec y)
311: {

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

326:   (*w->ops->pointwisemax)(w,x,y);
327:   PetscObjectStateIncrease((PetscObject)w);
328:   return(0);
329: }


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

337:    Collective on Vec

339:    Input Parameters:
340: .  x, y  - the vectors

342:    Output Parameter:
343: .  w - the result

345:    Level: advanced

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

350:    Concepts: vector^pointwise multiply

352: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
353: @*/
354: PetscErrorCode  VecPointwiseMin(Vec w,Vec x,Vec y)
355: {

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

370:   (*w->ops->pointwisemin)(w,x,y);
371:   PetscObjectStateIncrease((PetscObject)w);
372:   return(0);
373: }

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

380:    Collective on Vec

382:    Input Parameters:
383: .  x, y  - the vectors

385:    Output Parameter:
386: .  w - the result

388:    Level: advanced

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

392:    Concepts: vector^pointwise multiply

394: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
395: @*/
396: PetscErrorCode  VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
397: {

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

412:   (*w->ops->pointwisemaxabs)(w,x,y);
413:   PetscObjectStateIncrease((PetscObject)w);
414:   return(0);
415: }

419: /*@
420:    VecPointwiseDivide - Computes the componentwise division w = x/y.

422:    Collective on Vec

424:    Input Parameters:
425: .  x, y  - the vectors

427:    Output Parameter:
428: .  w - the result

430:    Level: advanced

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

434:    Concepts: vector^pointwise divide

436: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
437: @*/
438: PetscErrorCode  VecPointwiseDivide(Vec w,Vec x,Vec y)
439: {

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

454:   (*w->ops->pointwisedivide)(w,x,y);
455:   PetscObjectStateIncrease((PetscObject)w);
456:   return(0);
457: }


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

465:    Collective on Vec

467:    Input Parameters:
468: .  v - a vector to mimic

470:    Output Parameter:
471: .  newv - location to put new vector

473:    Notes:
474:    VecDuplicate() does not copy the vector, but rather allocates storage
475:    for the new vector.  Use VecCopy() to copy a vector.

477:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
478:    vectors.

480:    Level: beginner

482: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
483: @*/
484: PetscErrorCode  VecDuplicate(Vec v,Vec *newv)
485: {

492:   (*v->ops->duplicate)(v,newv);
493:   PetscObjectStateIncrease((PetscObject)*newv);
494:   return(0);
495: }

499: /*@
500:    VecDestroy - Destroys a vector.

502:    Collective on Vec

504:    Input Parameters:
505: .  v  - the vector

507:    Level: beginner

509: .seealso: VecDuplicate(), VecDestroyVecs()
510: @*/
511: PetscErrorCode  VecDestroy(Vec v)
512: {

517:   if (--((PetscObject)v)->refct > 0) return(0);
518:   /* destroy the internal part */
519:   if (v->ops->destroy) {
520:     (*v->ops->destroy)(v);
521:   }
522:   /* destroy the external/common part */
523:   if (v->mapping) {
524:     ISLocalToGlobalMappingDestroy(v->mapping);
525:   }
526:   if (v->bmapping) {
527:     ISLocalToGlobalMappingDestroy(v->bmapping);
528:   }
529:   PetscLayoutDestroy(v->map);
530:   PetscHeaderDestroy(v);
531:   return(0);
532: }

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

539:    Collective on Vec

541:    Input Parameters:
542: +  m - the number of vectors to obtain
543: -  v - a vector to mimic

545:    Output Parameter:
546: .  V - location to put pointer to array of vectors

548:    Notes:
549:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
550:    vector.

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

557:    Level: intermediate

559: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
560: @*/
561: PetscErrorCode  VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
562: {

569:   (*v->ops->duplicatevecs)(v, m,V);
570:   return(0);
571: }

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

578:    Collective on Vec

580:    Input Parameters:
581: +  vv - pointer to array of vector pointers
582: -  m - the number of vectors previously obtained

584:    Fortran Note:
585:    The Fortran interface is slightly different from that given below.
586:    See the Fortran chapter of the users manual and
587:    petsc/src/vec/examples for details.

589:    Level: intermediate

591: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
592: @*/
593: PetscErrorCode  VecDestroyVecs(Vec vv[],PetscInt m)
594: {

601:   (*(*vv)->ops->destroyvecs)(vv,m);
602:   return(0);
603: }

605: #undef  __FUNCT__
607: /*@
608:   VecViewFromOptions - This function visualizes the vector based upon user options.

610:   Collective on Vec

612:   Input Parameters:
613: . vec   - The vector
614: . title - The title (currently ignored)

616:   Level: intermediate

618: .keywords: Vec, view, options, database
619: .seealso: VecSetFromOptions(), VecView()
620: @*/
621: PetscErrorCode  VecViewFromOptions(Vec vec, const char *title)
622: {

626:   VecView_Private(vec);
627:   return(0);
628: }

632: /*@C
633:    VecView - Views a vector object.

635:    Collective on Vec

637:    Input Parameters:
638: +  vec - the vector
639: -  viewer - an optional visualization context

641:    Notes:
642:    The available visualization contexts include
643: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
644: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
645:          output where only the first processor opens
646:          the file.  All other processors send their
647:          data to the first processor to print.

649:    You can change the format the vector is printed using the
650:    option PetscViewerSetFormat().

652:    The user can open alternative visualization contexts with
653: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
654: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
655:          specified file; corresponding input uses VecLoad()
656: .    PetscViewerDrawOpen() - Outputs vector to an X window display
657: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

659:    The user can call PetscViewerSetFormat() to specify the output
660:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
661:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
662: +    PETSC_VIEWER_DEFAULT - default, prints vector contents
663: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
664: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
665: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
666:          format common among all vector types

668:    Notes for HDF5 Viewer: the name of the Vec (given with PetscObjectSetName() is the name that is used
669:    for the object in the HDF5 file. If you wish to store the same vector to the HDF5 viewer (with different values,
670:    obviously) several times, you must change its name each time before calling the VecView(). The name you use
671:    here should equal the name that you use in the Vec object that you use with VecLoadIntoVector().

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

676:    Level: beginner

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

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

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

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

718: /*@
719:    VecGetSize - Returns the global number of elements of the vector.

721:    Not Collective

723:    Input Parameter:
724: .  x - the vector

726:    Output Parameters:
727: .  size - the global length of the vector

729:    Level: beginner

731:    Concepts: vector^local size

733: .seealso: VecGetLocalSize()
734: @*/
735: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
736: {

743:   (*x->ops->getsize)(x,size);
744:   return(0);
745: }

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

754:    Not Collective

756:    Input Parameter:
757: .  x - the vector

759:    Output Parameter:
760: .  size - the length of the local piece of the vector

762:    Level: beginner

764:    Concepts: vector^size

766: .seealso: VecGetSize()
767: @*/
768: PetscErrorCode  VecGetLocalSize(Vec x,PetscInt *size)
769: {

776:   (*x->ops->getlocalsize)(x,size);
777:   return(0);
778: }

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

789:    Not Collective

791:    Input Parameter:
792: .  x - the vector

794:    Output Parameters:
795: +  low - the first local element, pass in PETSC_NULL if not interested
796: -  high - one more than the last local element, pass in PETSC_NULL if not interested

798:    Note:
799:    The high argument is one more than the last element stored locally.

801:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

803:    Level: beginner

805:    Concepts: ownership^of vectors
806:    Concepts: vector^ownership of elements

808: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
809: @*/
810: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
811: {
817:   if (low)  *low  = x->map->rstart;
818:   if (high) *high = x->map->rend;
819:   return(0);
820: }

824: /*@C
825:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor,
826:    assuming that the vectors are laid out with the
827:    first n1 elements on the first processor, next n2 elements on the
828:    second, etc.  For certain parallel layouts this range may not be
829:    well defined.

831:    Not Collective

833:    Input Parameter:
834: .  x - the vector

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

839:    Note:
840:    The high argument is one more than the last element stored locally.

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

844:    Level: beginner

846:    Concepts: ownership^of vectors
847:    Concepts: vector^ownership of elements

849: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
850: @*/
851: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
852: {

858:   PetscLayoutGetRanges(x->map,ranges);
859:   return(0);
860: }

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

867:    Collective on Vec

869:    Input Parameter:
870: +  x - the vector
871: .  op - the option
872: -  flag - turn the option on or off

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

883:    Level: intermediate

885: @*/
886: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscTruth flag)
887: {

893:   if (x->ops->setoption) {
894:     (*x->ops->setoption)(x,op,flag);
895:   }
896:   return(0);
897: }

901: /* Default routines for obtaining and releasing; */
902: /* may be used by any implementation */
903: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
904: {
906:   PetscInt       i;

911:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
912:   PetscMalloc(m*sizeof(Vec*),V);
913:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
914:   return(0);
915: }

919: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
920: {
922:   PetscInt       i;

926:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
927:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
928:   PetscFree(v);
929:   return(0);
930: }

934: /*@
935:    VecResetArray - Resets a vector to use its default memory. Call this
936:    after the use of VecPlaceArray().

938:    Not Collective

940:    Input Parameters:
941: .  vec - the vector

943:    Level: developer

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

947: @*/
948: PetscErrorCode  VecResetArray(Vec vec)
949: {

955:   if (vec->ops->resetarray) {
956:     (*vec->ops->resetarray)(vec);
957:   } else {
958:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
959:   }
960:   PetscObjectStateIncrease((PetscObject)vec);
961:   return(0);
962: }

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

970:   Collective on PetscViewer

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

976:   Level: intermediate

978:   Notes:
979:   The input file must contain the full global vector, as
980:   written by the routine VecView().

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

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

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

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

1005:    Concepts: vector^loading from file

1007: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
1008: @*/
1009: PetscErrorCode  VecLoadIntoVector(PetscViewer viewer,Vec vec)
1010: {
1011:   PetscErrorCode    ierr;
1012:   PetscViewerFormat format;

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

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

1043:    Collective on Vec

1045:    Input Parameter:
1046: .  vec - the vector

1048:    Output Parameter:
1049: .  vec - the vector reciprocal

1051:    Level: intermediate

1053:    Concepts: vector^reciprocal

1055: .seealso: VecLog(), VecExp(), VecSqrt()

1057: @*/
1058: PetscErrorCode  VecReciprocal(Vec vec)
1059: {

1065:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1066:   if (!vec->ops->reciprocal) {
1067:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
1068:   }
1069:   (*vec->ops->reciprocal)(vec);
1070:   PetscObjectStateIncrease((PetscObject)vec);
1071:   return(0);
1072: }

1076: PetscErrorCode  VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
1077: {
1080:   /* save the native version of the viewer */
1081:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
1082:     vec->ops->viewnative = vec->ops->view;
1083:   } else if (op == VECOP_LOADINTOVECTOR && !vec->ops->loadintovectornative) {
1084:     vec->ops->loadintovectornative = vec->ops->loadintovector;
1085:   }
1086:   (((void(**)(void))vec->ops)[(int)op]) = f;
1087:   return(0);
1088: }


1093: /*@
1094:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
1095:    used during the assembly process to store values that belong to
1096:    other processors.

1098:    Collective on Vec

1100:    Input Parameters:
1101: +  vec   - the vector
1102: .  size  - the initial size of the stash.
1103: -  bsize - the initial size of the block-stash(if used).

1105:    Options Database Keys:
1106: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
1107: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

1109:    Level: intermediate

1111:    Notes:
1112:      The block-stash is used for values set with VecSetValuesBlocked() while
1113:      the stash is used for values set with VecSetValues()

1115:      Run with the option -info and look for output of the form
1116:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
1117:      to determine the appropriate value, MM, to use for size and
1118:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
1119:      to determine the value, BMM to use for bsize

1121:    Concepts: vector^stash
1122:    Concepts: stash^vector

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

1126: @*/
1127: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
1128: {

1133:   VecStashSetInitialSize_Private(&vec->stash,size);
1134:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
1135:   return(0);
1136: }

1140: /*@
1141:    VecConjugate - Conjugates a vector.

1143:    Collective on Vec

1145:    Input Parameters:
1146: .  x - the vector

1148:    Level: intermediate

1150:    Concepts: vector^conjugate

1152: @*/
1153: PetscErrorCode  VecConjugate(Vec x)
1154: {
1155: #ifdef PETSC_USE_COMPLEX

1161:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1162:   (*x->ops->conjugate)(x);
1163:   /* we need to copy norms here */
1164:   PetscObjectStateIncrease((PetscObject)x);
1165:   return(0);
1166: #else
1167:   return(0);
1168: #endif
1169: }

1173: /*@
1174:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1176:    Collective on Vec

1178:    Input Parameters:
1179: .  x, y  - the vectors

1181:    Output Parameter:
1182: .  w - the result

1184:    Level: advanced

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

1188:    Concepts: vector^pointwise multiply

1190: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1191: @*/
1192: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
1193: {

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

1207:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1208:   (*w->ops->pointwisemult)(w,x,y);
1209:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1210:   PetscObjectStateIncrease((PetscObject)w);
1211:   return(0);
1212: }

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

1219:    Collective on Vec

1221:    Input Parameters:
1222: +  x  - the vector
1223: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
1224:           it will create one internally.

1226:    Output Parameter:
1227: .  x  - the vector

1229:    Example of Usage:
1230: .vb
1231:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
1232:      VecSetRandom(x,rctx);
1233:      PetscRandomDestroy(rctx);
1234: .ve

1236:    Level: intermediate

1238:    Concepts: vector^setting to random
1239:    Concepts: random^vector

1241: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
1242: @*/
1243: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
1244: {
1246:   PetscRandom    randObj = PETSC_NULL;

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

1254:   if (!rctx) {
1255:     MPI_Comm    comm;
1256:     PetscObjectGetComm((PetscObject)x,&comm);
1257:     PetscRandomCreate(comm,&randObj);
1258:     PetscRandomSetFromOptions(randObj);
1259:     rctx = randObj;
1260:   }

1262:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1263:   (*x->ops->setrandom)(x,rctx);
1264:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);

1266:   if (randObj) {
1267:     PetscRandomDestroy(randObj);
1268:   }
1269:   PetscObjectStateIncrease((PetscObject)x);
1270:   return(0);
1271: }

1275: /*@
1276:   VecZeroEntries - puts a 0.0 in each element of a vector

1278:   Collective on Vec

1280:   Input Parameter:
1281: . vec - The vector

1283:   Level: beginner

1285: .keywords: Vec, set, options, database
1286: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1287: @*/
1288: PetscErrorCode  VecZeroEntries(Vec vec)
1289: {
1292:   VecSet(vec,0);
1293:   return(0);
1294: }

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

1302:   Collective on Vec

1304:   Input Parameter:
1305: . vec - The vector

1307:   Level: intermediate

1309: .keywords: Vec, set, options, database, type
1310: .seealso: VecSetFromOptions(), VecSetType()
1311: */
1312: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
1313: {
1314:   PetscTruth     opt;
1315:   const VecType  defaultType;
1316:   char           typeName[256];
1317:   PetscMPIInt    size;

1321:   if (((PetscObject)vec)->type_name) {
1322:     defaultType = ((PetscObject)vec)->type_name;
1323:   } else {
1324:     MPI_Comm_size(((PetscObject)vec)->comm, &size);
1325:     if (size > 1) {
1326:       defaultType = VECMPI;
1327:     } else {
1328:       defaultType = VECSEQ;
1329:     }
1330:   }

1332:   if (!VecRegisterAllCalled) {VecRegisterAll(PETSC_NULL);}
1333:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
1334:   if (opt) {
1335:     VecSetType(vec, typeName);
1336:   } else {
1337:     VecSetType(vec, defaultType);
1338:   }
1339:   return(0);
1340: }

1344: /*@
1345:   VecSetFromOptions - Configures the vector from the options database.

1347:   Collective on Vec

1349:   Input Parameter:
1350: . vec - The vector

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

1355:   Level: beginner

1357:   Concepts: vectors^setting options
1358:   Concepts: vectors^setting type

1360: .keywords: Vec, set, options, database
1361: .seealso: VecCreate(), VecSetOptionsPrefix()
1362: @*/
1363: PetscErrorCode  VecSetFromOptions(Vec vec)
1364: {


1370:   PetscOptionsBegin(((PetscObject)vec)->comm, ((PetscObject)vec)->prefix, "Vector options", "Vec");
1371:     /* Handle vector type options */
1372:     VecSetTypeFromOptions_Private(vec);

1374:     /* Handle specific vector options */
1375:     if (vec->ops->setfromoptions) {
1376:       (*vec->ops->setfromoptions)(vec);
1377:     }
1378:   PetscOptionsEnd();

1380:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1381:   return(0);
1382: }

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

1389:   Collective on Vec

1391:   Input Parameters:
1392: + v - the vector
1393: . n - the local size (or PETSC_DECIDE to have it set)
1394: - N - the global size (or PETSC_DECIDE)

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

1400:   Level: intermediate

1402: .seealso: VecGetSize(), PetscSplitOwnership()
1403: @*/
1404: PetscErrorCode  VecSetSizes(Vec v, PetscInt n, PetscInt N)
1405: {

1410:   if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
1411:   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);
1412:   v->map->n = n;
1413:   v->map->N = N;
1414:   if (v->ops->create) {
1415:     (*v->ops->create)(v);
1416:     v->ops->create = 0;
1417:   }
1418:   return(0);
1419: }

1423: /*@
1424:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
1425:    and VecSetValuesBlockedLocal().

1427:    Collective on Vec

1429:    Input Parameter:
1430: +  v - the vector
1431: -  bs - the blocksize

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

1436:    Level: advanced

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

1440:   Concepts: block size^vectors
1441: @*/
1442: PetscErrorCode  VecSetBlockSize(Vec v,PetscInt bs)
1443: {
1446:   if (bs <= 0) bs = 1;
1447:   if (bs == v->map->bs) return(0);
1448:   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);
1449:   if (v->map->n != -1 && v->map->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
1450:    Try setting blocksize before setting the vector type",v->map->n,bs);

1452:   v->map->bs   = bs;
1453:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
1454:   return(0);
1455: }

1459: /*@
1460:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
1461:    and VecSetValuesBlockedLocal().

1463:    Collective on Vec

1465:    Input Parameter:
1466: .  v - the vector

1468:    Output Parameter:
1469: .  bs - the blocksize

1471:    Notes:
1472:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1474:    Level: advanced

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

1478:    Concepts: vector^block size
1479:    Concepts: block^vector

1481: @*/
1482: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1483: {
1487:   *bs = v->map->bs;
1488:   return(0);
1489: }

1493: /*@
1494:    VecValid - Checks whether a vector object is valid.

1496:    Not Collective

1498:    Input Parameter:
1499: .  v - the object to check

1501:    Output Parameter:
1502: .  flg - flag indicating vector status, either
1503:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

1505:    Level: developer

1507: @*/
1508: PetscErrorCode  VecValid(Vec v,PetscTruth *flg)
1509: {
1512:   if (!v)                                          *flg = PETSC_FALSE;
1513:   else if (((PetscObject)v)->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
1514:   else                                             *flg = PETSC_TRUE;
1515:   return(0);
1516: }

1520: /*@C
1521:    VecSetOptionsPrefix - Sets the prefix used for searching for all
1522:    Vec options in the database.

1524:    Collective on Vec

1526:    Input Parameter:
1527: +  v - the Vec context
1528: -  prefix - the prefix to prepend to all option names

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

1534:    Level: advanced

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

1538: .seealso: VecSetFromOptions()
1539: @*/
1540: PetscErrorCode  VecSetOptionsPrefix(Vec v,const char prefix[])
1541: {

1546:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1547:   return(0);
1548: }

1552: /*@C
1553:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all
1554:    Vec options in the database.

1556:    Collective on Vec

1558:    Input Parameters:
1559: +  v - the Vec context
1560: -  prefix - the prefix to prepend to all option names

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

1566:    Level: advanced

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

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

1578:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
1579:   return(0);
1580: }

1584: /*@C
1585:    VecGetOptionsPrefix - Sets the prefix used for searching for all
1586:    Vec options in the database.

1588:    Not Collective

1590:    Input Parameter:
1591: .  v - the Vec context

1593:    Output Parameter:
1594: .  prefix - pointer to the prefix string used

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

1599:    Level: advanced

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

1603: .seealso: VecAppendOptionsPrefix()
1604: @*/
1605: PetscErrorCode  VecGetOptionsPrefix(Vec v,const char *prefix[])
1606: {

1611:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1612:   return(0);
1613: }

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

1620:    Collective on Vec

1622:    Input Parameters:
1623: .  v - the Vec context

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

1629:    Level: advanced

1631: .keywords: Vec, setup

1633: .seealso: VecCreate(), VecDestroy()
1634: @*/
1635: PetscErrorCode  VecSetUp(Vec v)
1636: {
1637:   PetscMPIInt    size;

1642:   if (!((PetscObject)v)->type_name) {
1643:     MPI_Comm_size(((PetscObject)v)->comm, &size);
1644:     if (size == 1) {
1645:       VecSetType(v, VECSEQ);
1646:     } else {
1647:       VecSetType(v, VECMPI);
1648:     }
1649:   }
1650:   return(0);
1651: }

1653: /*
1654:     These currently expose the PetscScalar/PetscReal in updating the
1655:     cached norm. If we push those down into the implementation these
1656:     will become independent of PetscScalar/PetscReal
1657: */

1661: /*@
1662:    VecCopy - Copies a vector. y <- x

1664:    Collective on Vec

1666:    Input Parameter:
1667: .  x - the vector

1669:    Output Parameter:
1670: .  y - the copy

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

1676:    Level: beginner

1678: .seealso: VecDuplicate()
1679: @*/
1680: PetscErrorCode  VecCopy(Vec x,Vec y)
1681: {
1682:   PetscTruth     flgs[4];
1683:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
1685:   PetscInt       i;

1692:   if (x == y) return(0);
1693:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1694:   if (x->map->n != y->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1696:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1697:   (*x->ops->copy)(x,y);


1700:   /*
1701:    * Update cached data
1702:   */
1703:   /* in general we consider this object touched */
1704:   PetscObjectStateIncrease((PetscObject)y);

1706:   for (i=0; i<4; i++) {
1707:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
1708:   }
1709:   for (i=0; i<4; i++) {
1710:     if (flgs[i]) {
1711:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
1712:     }
1713:   }

1715:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1716:   return(0);
1717: }

1721: /*@
1722:    VecSwap - Swaps the vectors x and y.

1724:    Collective on Vec

1726:    Input Parameters:
1727: .  x, y  - the vectors

1729:    Level: advanced

1731:    Concepts: vector^swapping values

1733: @*/
1734: PetscErrorCode  VecSwap(Vec x,Vec y)
1735: {
1736:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
1737:   PetscTruth     flgxs[4],flgys[4];
1739:   PetscInt       i;

1747:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1748:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1749:   if (x->map->N != y->map->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1750:   if (x->map->n != y->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1752:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1753:   (*x->ops->swap)(x,y);

1755:   /* See if we have cached norms */
1756:   for (i=0; i<4; i++) {
1757:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
1758:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
1759:   }
1760:   for (i=0; i<4; i++) {
1761:     if (flgxs[i]) {
1762:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
1763:     }
1764:     if (flgys[i]) {
1765:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
1766:     }
1767:   }
1768:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
1769:   return(0);
1770: }

1774: /*@
1775:    VecStashView - Prints the entries in the vector stash and block stash.

1777:    Collective on Vec

1779:    Input Parameters:
1780: +  v - the vector
1781: -  viewer - the viewer

1783:    Level: advanced

1785:    Concepts: vector^stash
1786:    Concepts: stash^vector

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

1790: @*/
1791: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
1792: {
1794:   PetscMPIInt    rank;
1795:   PetscInt       i,j;
1796:   PetscTruth     match;
1797:   VecStash       *s;
1798:   PetscScalar    val;


1805:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
1806:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
1807:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
1808:   MPI_Comm_rank(((PetscObject)v)->comm,&rank);
1809:   s = &v->bstash;

1811:   /* print block stash */
1812:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
1813:   for (i=0; i<s->n; i++) {
1814:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
1815:     for (j=0; j<s->bs; j++) {
1816:       val = s->array[i*s->bs+j];
1817: #if defined(PETSC_USE_COMPLEX)
1818:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
1819: #else
1820:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
1821: #endif
1822:     }
1823:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
1824:   }
1825:   PetscViewerFlush(viewer);

1827:   s = &v->stash;

1829:   /* print basic stash */
1830:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
1831:   for (i=0; i<s->n; i++) {
1832:     val = s->array[i];
1833: #if defined(PETSC_USE_COMPLEX)
1834:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
1835: #else
1836:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
1837: #endif
1838:   }
1839:   PetscViewerFlush(viewer);

1841:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1842:   return(0);
1843: }