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: @*/
1056: PetscErrorCode  VecReciprocal(Vec vec)
1057: {

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

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


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

1096:    Collective on Vec

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

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

1107:    Level: intermediate

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

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

1119:    Concepts: vector^stash
1120:    Concepts: stash^vector

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

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

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

1138: /*@
1139:    VecConjugate - Conjugates a vector.

1141:    Collective on Vec

1143:    Input Parameters:
1144: .  x - the vector

1146:    Level: intermediate

1148:    Concepts: vector^conjugate

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

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

1171: /*@
1172:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1174:    Collective on Vec

1176:    Input Parameters:
1177: .  x, y  - the vectors

1179:    Output Parameter:
1180: .  w - the result

1182:    Level: advanced

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

1186:    Concepts: vector^pointwise multiply

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

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

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

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

1217:    Collective on Vec

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

1224:    Output Parameter:
1225: .  x  - the vector

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

1234:    Level: intermediate

1236:    Concepts: vector^setting to random
1237:    Concepts: random^vector

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

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

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

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

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

1273: /*@
1274:   VecZeroEntries - puts a 0.0 in each element of a vector

1276:   Collective on Vec

1278:   Input Parameter:
1279: . vec - The vector

1281:   Level: beginner

1283: .keywords: Vec, set, options, database
1284: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
1285: @*/
1286: PetscErrorCode  VecZeroEntries(Vec vec)
1287: {
1290:   VecSet(vec,0);
1291:   return(0);
1292: }

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

1300:   Collective on Vec

1302:   Input Parameter:
1303: . vec - The vector

1305:   Level: intermediate

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

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

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

1342: /*@
1343:   VecSetFromOptions - Configures the vector from the options database.

1345:   Collective on Vec

1347:   Input Parameter:
1348: . vec - The vector

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

1353:   Level: beginner

1355:   Concepts: vectors^setting options
1356:   Concepts: vectors^setting type

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


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

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

1378:   VecViewFromOptions(vec, ((PetscObject)vec)->name);
1379:   return(0);
1380: }

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

1387:   Collective on Vec

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

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

1398:   Level: intermediate

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

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

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

1425:    Collective on Vec

1427:    Input Parameter:
1428: +  v - the vector
1429: -  bs - the blocksize

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

1434:    Level: advanced

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

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

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

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

1461:    Collective on Vec

1463:    Input Parameter:
1464: .  v - the vector

1466:    Output Parameter:
1467: .  bs - the blocksize

1469:    Notes:
1470:    All vectors obtained by VecDuplicate() inherit the same blocksize.

1472:    Level: advanced

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

1476:    Concepts: vector^block size
1477:    Concepts: block^vector

1479: @*/
1480: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
1481: {
1485:   *bs = v->map->bs;
1486:   return(0);
1487: }

1491: /*@
1492:    VecValid - Checks whether a vector object is valid.

1494:    Not Collective

1496:    Input Parameter:
1497: .  v - the object to check

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

1503:    Level: developer

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

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

1522:    Collective on Vec

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

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

1532:    Level: advanced

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

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

1544:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
1545:   return(0);
1546: }

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

1554:    Collective on Vec

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

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

1564:    Level: advanced

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

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

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

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

1586:    Not Collective

1588:    Input Parameter:
1589: .  v - the Vec context

1591:    Output Parameter:
1592: .  prefix - pointer to the prefix string used

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

1597:    Level: advanced

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

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

1609:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
1610:   return(0);
1611: }

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

1618:    Collective on Vec

1620:    Input Parameters:
1621: .  v - the Vec context

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

1627:    Level: advanced

1629: .keywords: Vec, setup

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

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

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

1659: /*@
1660:    VecCopy - Copies a vector. y <- x

1662:    Collective on Vec

1664:    Input Parameter:
1665: .  x - the vector

1667:    Output Parameter:
1668: .  y - the copy

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

1674:    Level: beginner

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

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

1694:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
1695:   (*x->ops->copy)(x,y);


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

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

1713:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
1714:   return(0);
1715: }

1719: /*@
1720:    VecSwap - Swaps the vectors x and y.

1722:    Collective on Vec

1724:    Input Parameters:
1725: .  x, y  - the vectors

1727:    Level: advanced

1729:    Concepts: vector^swapping values

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

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

1750:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
1751:   (*x->ops->swap)(x,y);

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

1772: /*@
1773:    VecStashView - Prints the entries in the vector stash and block stash.

1775:    Collective on Vec

1777:    Input Parameters:
1778: +  v - the vector
1779: -  viewer - the viewer

1781:    Level: advanced

1783:    Concepts: vector^stash
1784:    Concepts: stash^vector

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

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


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

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

1825:   s = &v->stash;

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

1839:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
1840:   return(0);
1841: }