Actual source code: vector.c

  1: /*
  2:      Provides the interface functions for all vector operations.
  3:    These are the vector functions the user calls.
  4: */
 5:  #include vecimpl.h

  7: /* Logging support */
  8: PetscCookie VEC_COOKIE = 0;
  9: PetscEvent    VEC_View = 0, VEC_Max = 0, VEC_Min = 0, VEC_DotBarrier = 0, VEC_Dot = 0, VEC_MDotBarrier = 0, VEC_MDot = 0, VEC_TDot = 0;
 10: PetscEvent    VEC_Norm = 0, VEC_Normalize = 0, VEC_Scale = 0, VEC_Copy = 0, VEC_Set = 0, VEC_AXPY = 0, VEC_AYPX = 0, VEC_WAXPY = 0;
 11: PetscEvent    VEC_MTDot = 0, VEC_NormBarrier = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
 12: PetscEvent    VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0;
 13: PetscEvent    VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;

 15: /* ugly globals for VecSetValue() and VecSetValueLocal() */
 16: PetscInt    VecSetValue_Row = 0;
 17: PetscScalar VecSetValue_Value = 0.0;

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

 25:   Collective on Vec

 27:   Input Parameter:
 28: . vec - The vector

 30:   Level: intermediate

 32: .keywords: Vec, set, options, database, type
 33: .seealso: VecSetFromOptions(), VecSetType()
 34: */
 35: static PetscErrorCode VecSetTypeFromOptions_Private(Vec vec)
 36: {
 37:   PetscTruth     opt;
 38:   const char     *defaultType;
 39:   char           typeName[256];
 40:   PetscMPIInt    size;

 44:   if (vec->type_name) {
 45:     defaultType = vec->type_name;
 46:   } else {
 47:     MPI_Comm_size(vec->comm, &size);
 48:     if (size > 1) {
 49:       defaultType = VECMPI;
 50:     } else {
 51:       defaultType = VECSEQ;
 52:     }
 53:   }

 55:   if (!VecRegisterAllCalled) {
 56:     VecRegisterAll(PETSC_NULL);
 57:   }
 58:   PetscOptionsList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
 59:   if (opt) {
 60:     VecSetType(vec, typeName);
 61:   } else {
 62:     VecSetType(vec, defaultType);
 63:   }
 64:   return(0);
 65: }

 69: /*@C
 70:   VecSetFromOptions - Configures the vector from the options database.

 72:   Collective on Vec

 74:   Input Parameter:
 75: . vec - The vector

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

 80:   Level: beginner

 82:   Concepts: vectors^setting options
 83:   Concepts: vectors^setting type

 85: .keywords: Vec, set, options, database
 86: .seealso: VecCreate(), VecPrintHelp(), VecSetOptionsPrefix()
 87: @*/
 88: PetscErrorCode VecSetFromOptions(Vec vec)
 89: {
 90:   PetscTruth     opt;


 96:   PetscOptionsBegin(vec->comm, vec->prefix, "Vector options", "Vec");

 98:   /* Handle generic vector options */
 99:   PetscOptionsHasName(PETSC_NULL, "-help", &opt);
100:   if (opt) {
101:     VecPrintHelp(vec);
102:   }

104:   /* Handle vector type options */
105:   VecSetTypeFromOptions_Private(vec);

107:   /* Handle specific vector options */
108:   if (vec->ops->setfromoptions) {
109:     (*vec->ops->setfromoptions)(vec);
110:   }
111:   PetscOptionsEnd();

113:   VecViewFromOptions(vec, vec->name);
114:   return(0);
115: }

119: /*@
120:   VecPrintHelp - Prints some options for the Vec.

122:   Input Parameter:
123: . vec - The vector

125:   Options Database Keys:
126: $  -help, -h

128:   Level: intermediate

130: .keywords: Vec, help
131: .seealso: VecSetFromOptions()
132: @*/
133: PetscErrorCode VecPrintHelp(Vec vec)
134: {
137:   return(0);
138: }

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

145:   Collective on Vec

147:   Input Parameters:
148: + v - the vector
149: . n - the local size (or PETSC_DECIDE to have it set)
150: - N - the global size (or PETSC_DECIDE)

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

156:   Level: intermediate

158: .seealso: VecGetSize(), PetscSplitOwnership()
159: @*/
160: PetscErrorCode VecSetSizes(Vec v, PetscInt n, PetscInt N)
161: {
164:   if (N > 0 && n > N) SETERRQ2(PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
165:   if ((v->n >= 0 || v->N >= 0) && (v->n != n || v->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->n,v->N);
166:   v->n = n;
167:   v->N = N;
168:   return(0);
169: }

173: /*@
174:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
175:    and VecSetValuesBlockedLocal().

177:    Collective on Vec

179:    Input Parameter:
180: +  v - the vector
181: -  bs - the blocksize

183:    Notes:
184:    All vectors obtained by VecDuplicate() inherit the same blocksize.

186:    Level: advanced

188: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecGetBlockSize()

190:   Concepts: block size^vectors
191: @*/
192: PetscErrorCode VecSetBlockSize(Vec v,PetscInt bs)
193: {
196:   if (bs <= 0) bs = 1;
197:   if (bs == v->bs) return(0);
198:   if (v->bs != -1) SETERRQ2(PETSC_ERR_ARG_WRONGSTATE,"Cannot reset blocksize. Current size %D new %D",v->bs,bs);
199:   if (v->N != -1 && v->N % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Vector length not divisible by blocksize %D %D",v->N,bs);
200:   if (v->n != -1 && v->n % bs) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local vector length not divisible by blocksize %D %D\n\
201:    Try setting blocksize before setting the vector type",v->n,bs);
202: 
203:   v->bs        = bs;
204:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
205:   return(0);
206: }

210: /*@
211:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
212:    and VecSetValuesBlockedLocal().

214:    Collective on Vec

216:    Input Parameter:
217: .  v - the vector

219:    Output Parameter:
220: .  bs - the blocksize

222:    Notes:
223:    All vectors obtained by VecDuplicate() inherit the same blocksize.

225:    Level: advanced

227: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMappingBlocked(), VecSetBlockSize()

229:    Concepts: vector^block size
230:    Concepts: block^vector

232: @*/
233: PetscErrorCode VecGetBlockSize(Vec v,PetscInt *bs)
234: {
238:   *bs = v->bs;
239:   return(0);
240: }

244: /*@
245:    VecValid - Checks whether a vector object is valid.

247:    Not Collective

249:    Input Parameter:
250: .  v - the object to check

252:    Output Parameter:
253:    flg - flag indicating vector status, either
254:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

256:    Level: developer

258: @*/
259: PetscErrorCode VecValid(Vec v,PetscTruth *flg)
260: {
263:   if (!v)                           *flg = PETSC_FALSE;
264:   else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
265:   else                              *flg = PETSC_TRUE;
266:   return(0);
267: }

271: /*@
272:    VecDot - Computes the vector dot product.

274:    Collective on Vec

276:    Input Parameters:
277: .  x, y - the vectors

279:    Output Parameter:
280: .  alpha - the dot product

282:    Performance Issues:
283: +    per-processor memory bandwidth
284: .    interprocessor latency
285: -    work load inbalance that causes certain processes to arrive much earlier than
286:      others

288:    Notes for Users of Complex Numbers:
289:    For complex vectors, VecDot() computes 
290: $     val = (x,y) = y^H x,
291:    where y^H denotes the conjugate transpose of y.

293:    Use VecTDot() for the indefinite form
294: $     val = (x,y) = y^T x,
295:    where y^T denotes the transpose of y.

297:    Level: intermediate

299:    Concepts: inner product
300:    Concepts: vector^inner product

302: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
303: @*/
304: PetscErrorCode VecDot(Vec x,Vec y,PetscScalar *val)
305: {

315:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
316:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

318:   PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
319:   (*x->ops->dot)(x,y,val);
320:   PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
321:   /*
322:      The next block is for incremental debugging
323:   */
324:   if (PetscCompare) {
325:     PetscMPIInt flag;
326:     MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
327:     if (flag != MPI_UNEQUAL) {
328:       PetscCompareScalar(*val);
329:     }
330:   }
331:   return(0);
332: }

336: /*@
337:    VecNorm  - Computes the vector norm.

339:    Collective on Vec

341:    Input Parameters:
342: +  x - the vector
343: -  type - one of NORM_1, NORM_2, NORM_INFINITY.  Also available
344:           NORM_1_AND_2, which computes both norms and stores them
345:           in a two element array.

347:    Output Parameter:
348: .  val - the norm 

350:    Notes:
351: $     NORM_1 denotes sum_i |x_i|
352: $     NORM_2 denotes sqrt(sum_i (x_i)^2)
353: $     NORM_INFINITY denotes max_i |x_i|

355:    Level: intermediate

357:    Performance Issues:
358: +    per-processor memory bandwidth
359: .    interprocessor latency
360: -    work load inbalance that causes certain processes to arrive much earlier than
361:      others

363:    Compile Option:
364:    PETSC_HAVE_SLOW_NRM2 will cause a C (loop unrolled) version of the norm to be used, rather
365:  than the BLAS. This should probably only be used when one is using the FORTRAN BLAS routines 
366:  (as opposed to vendor provided) because the FORTRAN BLAS NRM2() routine is very slow. 

368:    Concepts: norm
369:    Concepts: vector^norm

371: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), 
372:           VecNormBegin(), VecNormEnd()

374: @*/
375: PetscErrorCode VecNorm(Vec x,NormType type,PetscReal *val)
376: {
377:   PetscTruth     flg;
379:   PetscInt       type_id;


386:   /*
387:    * Cached data?
388:    */
389:   if (type!=NORM_1_AND_2) {
390:     VecNormComposedDataID(type,&type_id);
391:     PetscObjectGetRealComposedData((PetscObject)x,type_id,*val,flg);
392:     if (flg) return(0);
393:   }
394: 

396:   PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
397:   (*x->ops->norm)(x,type,val);
398:   PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);

400:   /*
401:      The next block is for incremental debugging
402:   */
403:   if (PetscCompare) {
404:     PetscMPIInt flag;
405:     MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
406:     if (flag != MPI_UNEQUAL) {
407:       PetscCompareDouble(*val);
408:     }
409:   }

411:   if (type!=NORM_1_AND_2) {
412:     PetscObjectSetRealComposedData((PetscObject)x,type_id,*val);
413:   }

415:   return(0);
416: }

420: PetscErrorCode VecNormComposedDataID(NormType type,PetscInt *type_id)
421: {
422:   static PetscInt id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
423:   PetscErrorCode  ierr;

426:   switch (type) {
427:   case NORM_1 :
428:     if (id_norm1==-1) {
429:       PetscRegisterComposedData(&id_norm1);}
430:     *type_id = id_norm1; break;
431:   case NORM_2 :
432:     if (id_norm2==-1) {
433:       PetscRegisterComposedData(&id_norm2);}
434:     *type_id = id_norm2; break;
435:   case NORM_1_AND_2 :
436:     /* we don't handle this one yet */
437:     if (id_norm1==-1) {
438:       PetscRegisterComposedData(&id_norm1);}
439:     if (id_norm2==-1) {
440:       PetscRegisterComposedData(&id_norm2);}
441:     *type_id = id_norm12; break;
442:   case NORM_INFINITY :
443:     if (id_normInf==-1) {
444:       PetscRegisterComposedData(&id_normInf);}
445:     *type_id = id_normInf; break;
446:   case NORM_FROBENIUS :
447:     if (id_normF==-1) {
448:       PetscRegisterComposedData(&id_normF);}
449:     *type_id = id_normF; break;
450:   }
451:   return(0);
452: }

456: /*@
457:    VecNormalize - Normalizes a vector by 2-norm. 

459:    Collective on Vec

461:    Input Parameters:
462: +  x - the vector

464:    Output Parameter:
465: .  x - the normalized vector
466: -  val - the vector norm before normalization

468:    Level: intermediate

470:    Concepts: vector^normalizing
471:    Concepts: normalizing^vector

473: @*/
474: PetscErrorCode VecNormalize (Vec x,PetscReal *val)
475: {

482:   PetscLogEventBegin(VEC_Normalize,x,0,0,0);
483:   VecNorm(x,NORM_2,val);
484:   if (!*val) {
485:     PetscLogInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm");
486:   } else {
487:     PetscScalar tmp = 1.0/(*val);
488:     VecScale(&tmp,x);
489:   }

491:   PetscLogEventEnd(VEC_Normalize,x,0,0,0);
492:   return(0);
493: }

497: /*@C
498:    VecMax - Determines the maximum vector component and its location.

500:    Collective on Vec

502:    Input Parameter:
503: .  x - the vector

505:    Output Parameters:
506: +  val - the maximum component
507: -  p - the location of val

509:    Notes:
510:    Returns the value PETSC_MIN and p = -1 if the vector is of length 0.

512:    Level: intermediate

514:    Concepts: maximum^of vector
515:    Concepts: vector^maximum value

517: .seealso: VecNorm(), VecMin()
518: @*/
519: PetscErrorCode VecMax(Vec x,PetscInt *p,PetscReal *val)
520: {

527:   PetscLogEventBegin(VEC_Max,x,0,0,0);
528:   (*x->ops->max)(x,p,val);
529:   PetscLogEventEnd(VEC_Max,x,0,0,0);
530:   return(0);
531: }

535: /*@
536:    VecMin - Determines the minimum vector component and its location.

538:    Collective on Vec

540:    Input Parameters:
541: .  x - the vector

543:    Output Parameter:
544: +  val - the minimum component
545: -  p - the location of val

547:    Level: intermediate

549:    Notes:
550:    Returns the value PETSC_MAX and p = -1 if the vector is of length 0.

552:    Concepts: minimum^of vector
553:    Concepts: vector^minimum entry

555: .seealso: VecMax()
556: @*/
557: PetscErrorCode VecMin(Vec x,PetscInt *p,PetscReal *val)
558: {

565:   PetscLogEventBegin(VEC_Min,x,0,0,0);
566:   (*x->ops->min)(x,p,val);
567:   PetscLogEventEnd(VEC_Min,x,0,0,0);
568:   return(0);
569: }

573: /*@
574:    VecTDot - Computes an indefinite vector dot product. That is, this
575:    routine does NOT use the complex conjugate.

577:    Collective on Vec

579:    Input Parameters:
580: .  x, y - the vectors

582:    Output Parameter:
583: .  val - the dot product

585:    Notes for Users of Complex Numbers:
586:    For complex vectors, VecTDot() computes the indefinite form
587: $     val = (x,y) = y^T x,
588:    where y^T denotes the transpose of y.

590:    Use VecDot() for the inner product
591: $     val = (x,y) = y^H x,
592:    where y^H denotes the conjugate transpose of y.

594:    Level: intermediate

596:    Concepts: inner product^non-Hermitian
597:    Concepts: vector^inner product
598:    Concepts: non-Hermitian inner product

600: .seealso: VecDot(), VecMTDot()
601: @*/
602: PetscErrorCode VecTDot(Vec x,Vec y,PetscScalar *val)
603: {

613:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
614:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

616:   PetscLogEventBegin(VEC_TDot,x,y,0,0);
617:   (*x->ops->tdot)(x,y,val);
618:   PetscLogEventEnd(VEC_TDot,x,y,0,0);
619:   return(0);
620: }

624: /*@
625:    VecScale - Scales a vector. 

627:    Collective on Vec

629:    Input Parameters:
630: +  x - the vector
631: -  alpha - the scalar

633:    Output Parameter:
634: .  x - the scaled vector

636:    Note:
637:    For a vector with n components, VecScale() computes 
638: $      x[i] = alpha * x[i], for i=1,...,n.

640:    Level: intermediate

642:    Concepts: vector^scaling
643:    Concepts: scaling^vector

645: @*/
646: PetscErrorCode VecScale (const PetscScalar *alpha,Vec x)
647: {
648:   PetscReal      scale,norm1=0.0,norm2=0.0,normInf=0.0,normF=0.0;
649:   PetscTruth     flg1,flg2,flgInf,flgF;
651:   PetscInt       type_id1,type_id2,type_idInf,type_idF;

657:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
658:   PetscLogEventBegin(VEC_Scale,x,0,0,0);
659:   (*x->ops->scale)(alpha,x);

661:   /*
662:    * Update cached data
663:    */
664:   /* see if we have cached norms */
665:   /* 1 */
666:   VecNormComposedDataID(NORM_1,&type_id1);
667:   PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1,flg1);
668:   /* 2 */
669:   VecNormComposedDataID(NORM_2,&type_id2);
670:   PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2,flg2);
671:   /* inf */
672:   VecNormComposedDataID(NORM_INFINITY,&type_idInf);
673:   PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInf,flgInf);
674:   /* frobenius */
675:   VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
676:   PetscObjectGetRealComposedData((PetscObject)x,type_idF,normF,flgF);

678:   /* in general we consider this object touched */
679:   PetscObjectIncreaseState((PetscObject)x);

681:   /* however, norms can be simply updated */
682:   scale = PetscAbsScalar(*alpha);
683:   /* 1 */
684:   if (flg1) {
685:     PetscObjectSetRealComposedData((PetscObject)x,type_id1,scale*norm1);
686:   }
687:   /* 2 */
688:   if (flg2) {
689:     PetscObjectSetRealComposedData((PetscObject)x,type_id2,scale*norm2);
690:   }
691:   /* inf */
692:   if (flgInf) {
693:     PetscObjectSetRealComposedData((PetscObject)x,type_idInf,scale*normInf);
694:   }
695:   /* frobenius */
696:   if (flgF) {
697:     PetscObjectSetRealComposedData((PetscObject)x,type_idF,scale*normF);
698:   }

700:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
701:   return(0);
702: }

706: /*@
707:    VecCopy - Copies a vector. 

709:    Collective on Vec

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

714:    Output Parameter:
715: .  y - the copy

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

721:    Level: beginner

723: .seealso: VecDuplicate()
724: @*/
725: PetscErrorCode VecCopy(Vec x,Vec y)
726: {
727:   PetscTruth     flg;
728:   PetscReal      norm=0.0;
730:   PetscInt       type_id;

738:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
739:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

741:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
742:   (*x->ops->copy)(x,y);

744:   /*
745:    * Update cached data
746:    */
747:   /* in general we consider this object touched */
748:   PetscObjectIncreaseState((PetscObject)y);
749:   /* however, norms can be simply copied over */
750:   /* 2 */
751:   VecNormComposedDataID(NORM_2,&type_id);
752:   PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
753:   if (flg) {
754:     PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
755:   }
756:   /* 1 */
757:   VecNormComposedDataID(NORM_1,&type_id);
758:   PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
759:   if (flg) {
760:     PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
761:   }
762:   /* inf */
763:   VecNormComposedDataID(NORM_INFINITY,&type_id);
764:   PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
765:   if (flg) {
766:     PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
767:   }
768:   /* frobenius */
769:   VecNormComposedDataID(NORM_FROBENIUS,&type_id);
770:   PetscObjectGetRealComposedData((PetscObject)x,type_id,norm,flg);
771:   if (flg) {
772:     PetscObjectSetRealComposedData((PetscObject)y,type_id,norm);
773:   }

775:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
776:   return(0);
777: }

781: /*@
782:    VecSet - Sets all components of a vector to a single scalar value. 

784:    Collective on Vec

786:    Input Parameters:
787: +  alpha - the scalar
788: -  x  - the vector

790:    Output Parameter:
791: .  x  - the vector

793:    Note:
794:    For a vector of dimension n, VecSet() computes
795: $     x[i] = alpha, for i=1,...,n,
796:    so that all vector entries then equal the identical
797:    scalar value, alpha.  Use the more general routine
798:    VecSetValues() to set different vector entries.

800:    You CANNOT call this after you have called VecSetValues() but before you call 
801:    VecAssemblyBegin/End().

803:    Level: beginner

805: .seealso VecSetValues(), VecSetValuesBlocked(), VecSetRandom()

807:    Concepts: vector^setting to constant

809: @*/
810: PetscErrorCode VecSet(const PetscScalar *alpha,Vec x)
811: {
812:   PetscReal      val;
814:   PetscInt       type_id;

820:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"You cannot call this after you have called VecSetValues() but\n before you have called VecAssemblyBegin/End()");

822:   PetscLogEventBegin(VEC_Set,x,0,0,0);
823:   (*x->ops->set)(alpha,x);
824:   PetscLogEventEnd(VEC_Set,x,0,0,0);

826:   /*
827:    * Update cached data
828:    */
829:   /* in general we consider this object touched */
830:   PetscObjectIncreaseState((PetscObject)x);
831:   /* however, norms can be simply set */
832:   /* 1 */
833:   val = PetscAbsScalar(*alpha);
834:   VecNormComposedDataID(NORM_1,&type_id);
835:   PetscObjectSetRealComposedData((PetscObject)x,type_id,x->N * val);
836:   /* inf */
837:   VecNormComposedDataID(NORM_INFINITY,&type_id);
838:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
839:   /* 2 */
840:   val = sqrt((double)x->N) * val;
841:   VecNormComposedDataID(NORM_2,&type_id);
842:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
843:   /* frobenius */
844:   VecNormComposedDataID(NORM_FROBENIUS,&type_id);
845:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);

847:   return(0);
848: }

852: /*@C
853:    VecSetRandom - Sets all components of a vector to random numbers.

855:    Collective on Vec

857:    Input Parameters:
858: +  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
859:           it will create one internally.
860: -  x  - the vector

862:    Output Parameter:
863: .  x  - the vector

865:    Example of Usage:
866: .vb
867:      PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
868:      VecSetRandom(rctx,x);
869:      PetscRandomDestroy(rctx);
870: .ve

872:    Level: intermediate

874:    Concepts: vector^setting to random
875:    Concepts: random^vector

877: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
878: @*/
879: PetscErrorCode VecSetRandom(PetscRandom rctx,Vec x)
880: {
882:   PetscRandom    randObj = PETSC_NULL;

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

890:   if (!rctx) {
891:     MPI_Comm    comm;
892:     PetscObjectGetComm((PetscObject)x,&comm);
893:     PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
894:     rctx = randObj;
895:   }

897:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
898:   (*x->ops->setrandom)(rctx,x);
899:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
900: 
901:   if (randObj) {
902:     PetscRandomDestroy(randObj);
903:   }
904:   PetscObjectIncreaseState((PetscObject)x);
905:   return(0);
906: }

910: /*@
911:    VecAXPY - Computes y = alpha x + y. 

913:    Collective on Vec

915:    Input Parameters:
916: +  alpha - the scalar
917: -  x, y  - the vectors

919:    Output Parameter:
920: .  y - output vector

922:    Level: intermediate

924:    Concepts: vector^BLAS
925:    Concepts: BLAS

927: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
928: @*/
929: PetscErrorCode VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
930: {

940:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
941:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

943:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
944:   (*x->ops->axpy)(alpha,x,y);
945:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
946:   PetscObjectIncreaseState((PetscObject)y);
947:   return(0);
948: }

952: /*@
953:    VecAXPBY - Computes y = alpha x + beta y. 

955:    Collective on Vec

957:    Input Parameters:
958: +  alpha,beta - the scalars
959: -  x, y  - the vectors

961:    Output Parameter:
962: .  y - output vector

964:    Level: intermediate

966:    Concepts: BLAS
967:    Concepts: vector^BLAS

969: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
970: @*/
971: PetscErrorCode VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
972: {

983:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
984:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

986:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
987:   (*x->ops->axpby)(alpha,beta,x,y);
988:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
989:   PetscObjectIncreaseState((PetscObject)y);
990:   return(0);
991: }

995: /*@
996:    VecAYPX - Computes y = x + alpha y.

998:    Collective on Vec

1000:    Input Parameters:
1001: +  alpha - the scalar
1002: -  x, y  - the vectors

1004:    Output Parameter:
1005: .  y - output vector

1007:    Level: intermediate

1009:    Concepts: vector^BLAS
1010:    Concepts: BLAS

1012: .seealso: VecAXPY(), VecWAXPY()
1013: @*/
1014: PetscErrorCode VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
1015: {

1025:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1026:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1028:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1029:    (*x->ops->aypx)(alpha,x,y);
1030:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1031:   PetscObjectIncreaseState((PetscObject)y);
1032:   return(0);
1033: }

1037: /*@
1038:    VecSwap - Swaps the vectors x and y.

1040:    Collective on Vec

1042:    Input Parameters:
1043: .  x, y  - the vectors

1045:    Level: advanced

1047:    Concepts: vector^swapping values

1049: @*/
1050: PetscErrorCode VecSwap(Vec x,Vec y)
1051: {
1052:   PetscReal      norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1053:   PetscReal      norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1054:   PetscTruth     flg1x,flg2x,flgInfx,flgFx;
1055:   PetscTruth     flg1y,flg2y,flgInfy,flgFy;
1056:   PetscInt       type_id1,type_id2,type_idInf,type_idF;

1065:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1066:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1067:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1068:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1070:   PetscLogEventBegin(VEC_Swap,x,y,0,0);

1072:   /* See if we have cached norms */
1073:   /* 1 */
1074:   VecNormComposedDataID(NORM_1,&type_id1);
1075:   PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1x,flg1x);
1076:   PetscObjectGetRealComposedData((PetscObject)y,type_id1,norm1y,flg1y);
1077:   /* 2 */
1078:   VecNormComposedDataID(NORM_2,&type_id2);
1079:   PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2x,flg2x);
1080:   PetscObjectGetRealComposedData((PetscObject)y,type_id2,norm2y,flg2y);
1081:   /* inf */
1082:   VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1083:   PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInfx,flgInfx);
1084:   PetscObjectGetRealComposedData((PetscObject)y,type_idInf,normInfy,flgInfy);
1085:   /* frobenius */
1086:   VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1087:   PetscObjectGetRealComposedData((PetscObject)x,type_idF,normFx,flgFx);
1088:   PetscObjectGetRealComposedData((PetscObject)y,type_idF,normFy,flgFy);

1090:   /* Do the actual swap */
1091:   (*x->ops->swap)(x,y);
1092:   PetscObjectIncreaseState((PetscObject)x);
1093:   PetscObjectIncreaseState((PetscObject)y);

1095:   /* Swap any cached norms */
1096:   /* 1 */
1097:   if (flg1x) {
1098:     PetscObjectSetRealComposedData((PetscObject)y,type_id1,norm1x);
1099:   }
1100:   if (flg1y) {
1101:     PetscObjectSetRealComposedData((PetscObject)x,type_id1,norm1y);
1102:   }
1103:   /* 2 */
1104:   if (flg2x) {
1105:     PetscObjectSetRealComposedData((PetscObject)y,type_id2,norm2x);
1106:   }
1107:   if (flg2y) {
1108:     PetscObjectSetRealComposedData((PetscObject)x,type_id2,norm2y);
1109:   }
1110:   /* inf */
1111:   if (flgInfx) {
1112:     PetscObjectSetRealComposedData((PetscObject)y,type_idInf,normInfx);
1113:   }
1114:   if (flgInfy) {
1115:     PetscObjectSetRealComposedData((PetscObject)x,type_idInf,normInfy);
1116:   }
1117:   /* frobenius */
1118:   if (flgFx) {
1119:     PetscObjectSetRealComposedData((PetscObject)y,type_idF,normFx);
1120:   }
1121:   if (flgFy) {
1122:     PetscObjectSetRealComposedData((PetscObject)x,type_idF,normFy);
1123:   }

1125:   PetscLogEventEnd(VEC_Swap,x,y,0,0);

1127:   return(0);
1128: }

1132: /*@
1133:    VecWAXPY - Computes w = alpha x + y.

1135:    Collective on Vec

1137:    Input Parameters:
1138: +  alpha - the scalar
1139: -  x, y  - the vectors

1141:    Output Parameter:
1142: .  w - the result

1144:    Level: intermediate

1146:    Concepts: vector^BLAS
1147:    Concepts: BLAS

1149: .seealso: VecAXPY(), VecAYPX()
1150: @*/
1151: PetscErrorCode VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
1152: {

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

1168:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1169:    (*x->ops->waxpy)(alpha,x,y,w);
1170:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1171:   PetscObjectIncreaseState((PetscObject)w);
1172:   return(0);
1173: }

1177: /*@
1178:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1180:    Collective on Vec

1182:    Input Parameters:
1183: .  x, y  - the vectors

1185:    Output Parameter:
1186: .  w - the result

1188:    Level: advanced

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

1192:    Concepts: vector^pointwise multiply

1194: .seealso: VecPointwiseDivide()
1195: @*/
1196: PetscErrorCode VecPointwiseMult(Vec x,Vec y,Vec w)
1197: {

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

1212:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1213:   (*x->ops->pointwisemult)(x,y,w);
1214:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1215:   PetscObjectIncreaseState((PetscObject)w);
1216:   return(0);
1217: }

1221: /*@
1222:    VecPointwiseDivide - Computes the componentwise division w = x/y.

1224:    Collective on Vec

1226:    Input Parameters:
1227: .  x, y  - the vectors

1229:    Output Parameter:
1230: .  w - the result

1232:    Level: advanced

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

1236:    Concepts: vector^pointwise divide

1238: .seealso: VecPointwiseMult()
1239: @*/
1240: PetscErrorCode VecPointwiseDivide(Vec x,Vec y,Vec w)
1241: {

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

1256:   (*x->ops->pointwisedivide)(x,y,w);
1257:   PetscObjectIncreaseState((PetscObject)w);
1258:   return(0);
1259: }

1263: /*@
1264:    VecMaxPointwiseDivide - Computes the maximum of the componentwise division w = abs(x/y).

1266:    Collective on Vec

1268:    Input Parameters:
1269: .  x, y  - the vectors

1271:    Output Parameter:
1272: .  max - the result

1274:    Level: advanced

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

1278: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1279: @*/
1280: PetscErrorCode VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1281: {

1291:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1292:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1294:   (*x->ops->maxpointwisedivide)(x,y,max);
1295:   return(0);
1296: }

1300: /*@C
1301:    VecDuplicate - Creates a new vector of the same type as an existing vector.

1303:    Collective on Vec

1305:    Input Parameters:
1306: .  v - a vector to mimic

1308:    Output Parameter:
1309: .  newv - location to put new vector

1311:    Notes:
1312:    VecDuplicate() does not copy the vector, but rather allocates storage
1313:    for the new vector.  Use VecCopy() to copy a vector.

1315:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1316:    vectors. 

1318:    Level: beginner

1320: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1321: @*/
1322: PetscErrorCode VecDuplicate(Vec x,Vec *newv)
1323: {

1330:   (*x->ops->duplicate)(x,newv);
1331:   PetscObjectIncreaseState((PetscObject)*newv);
1332:   return(0);
1333: }

1337: /*@C
1338:    VecDestroy - Destroys a vector.

1340:    Collective on Vec

1342:    Input Parameters:
1343: .  v  - the vector

1345:    Level: beginner

1347: .seealso: VecDuplicate(), VecDestroyVecs()
1348: @*/
1349: PetscErrorCode VecDestroy(Vec v)
1350: {

1355:   if (--v->refct > 0) return(0);
1356:   /* destroy the internal part */
1357:   if (v->ops->destroy) {
1358:     (*v->ops->destroy)(v);
1359:   }
1360:   /* destroy the external/common part */
1361:   if (v->mapping) {
1362:     ISLocalToGlobalMappingDestroy(v->mapping);
1363:   }
1364:   if (v->bmapping) {
1365:     ISLocalToGlobalMappingDestroy(v->bmapping);
1366:   }
1367:   if (v->map) {
1368:     PetscMapDestroy(v->map);
1369:   }
1370:   PetscLogObjectDestroy(v);
1371:   PetscHeaderDestroy(v);
1372:   return(0);
1373: }

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

1380:    Collective on Vec

1382:    Input Parameters:
1383: +  m - the number of vectors to obtain
1384: -  v - a vector to mimic

1386:    Output Parameter:
1387: .  V - location to put pointer to array of vectors

1389:    Notes:
1390:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1391:    vector.

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

1398:    Level: intermediate

1400: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1401: @*/
1402: PetscErrorCode VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
1403: {

1410:   (*v->ops->duplicatevecs)(v, m,V);
1411:   return(0);
1412: }

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

1419:    Collective on Vec

1421:    Input Parameters:
1422: +  vv - pointer to array of vector pointers
1423: -  m - the number of vectors previously obtained

1425:    Fortran Note:
1426:    The Fortran interface is slightly different from that given below.
1427:    See the Fortran chapter of the users manual and 
1428:    petsc/src/vec/examples for details.

1430:    Level: intermediate

1432: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
1433: @*/
1434: PetscErrorCode VecDestroyVecs(Vec vv[],PetscInt m)
1435: {

1442:   (*(*vv)->ops->destroyvecs)(vv,m);
1443:   return(0);
1444: }


1449: /*@
1450:    VecSetValues - Inserts or adds values into certain locations of a vector. 

1452:    Input Parameters:
1453:    Not Collective

1455: +  x - vector to insert in
1456: .  ni - number of elements to add
1457: .  ix - indices where to add
1458: .  y - array of values
1459: -  iora - either INSERT_VALUES or ADD_VALUES, where
1460:    ADD_VALUES adds values to any existing entries, and
1461:    INSERT_VALUES replaces existing entries with new values

1463:    Notes: 
1464:    VecSetValues() sets x[ix[i]] = y[i], for i=0,...,ni-1.

1466:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1467:    options cannot be mixed without intervening calls to the assembly
1468:    routines.

1470:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
1471:    MUST be called after all calls to VecSetValues() have been completed.

1473:    VecSetValues() uses 0-based indices in Fortran as well as in C.

1475:    Negative indices may be passed in ix, these rows are 
1476:    simply ignored. This allows easily inserting element load matrices
1477:    with homogeneous Dirchlet boundary conditions that you don't want represented
1478:    in the vector.

1480:    Level: beginner

1482:    Concepts: vector^setting values

1484: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1485:            VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES
1486: @*/
1487: PetscErrorCode VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1488: {

1496:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1497:   (*x->ops->setvalues)(x,ni,ix,y,iora);
1498:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1499:   PetscObjectIncreaseState((PetscObject)x);
1500:   return(0);
1501: }

1505: /*@
1506:    VecSetValuesBlocked - Inserts or adds blocks of values into certain locations of a vector. 

1508:    Not Collective

1510:    Input Parameters:
1511: +  x - vector to insert in
1512: .  ni - number of blocks to add
1513: .  ix - indices where to add in block count, rather than element count
1514: .  y - array of values
1515: -  iora - either INSERT_VALUES or ADD_VALUES, where
1516:    ADD_VALUES adds values to any existing entries, and
1517:    INSERT_VALUES replaces existing entries with new values

1519:    Notes: 
1520:    VecSetValuesBlocked() sets x[bs*ix[i]+j] = y[bs*i+j], 
1521:    for j=0,...,bs, for i=0,...,ni-1. where bs was set with VecSetBlockSize().

1523:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
1524:    options cannot be mixed without intervening calls to the assembly
1525:    routines.

1527:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
1528:    MUST be called after all calls to VecSetValuesBlocked() have been completed.

1530:    VecSetValuesBlocked() uses 0-based indices in Fortran as well as in C.

1532:    Negative indices may be passed in ix, these rows are 
1533:    simply ignored. This allows easily inserting element load matrices
1534:    with homogeneous Dirchlet boundary conditions that you don't want represented
1535:    in the vector.

1537:    Level: intermediate

1539:    Concepts: vector^setting values blocked

1541: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1542:            VecSetValues()
1543: @*/
1544: PetscErrorCode VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1545: {

1553:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1554:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1555:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1556:   PetscObjectIncreaseState((PetscObject)x);
1557:   return(0);
1558: }

1562: /*@
1563:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1564:    by the routine VecSetValuesLocal() to allow users to insert vector entries
1565:    using a local (per-processor) numbering.

1567:    Collective on Vec

1569:    Input Parameters:
1570: +  x - vector
1571: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

1573:    Notes: 
1574:    All vectors obtained with VecDuplicate() from this vector inherit the same mapping.

1576:    Level: intermediate

1578:    Concepts: vector^setting values with local numbering

1580: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1581:            VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1582: @*/
1583: PetscErrorCode VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1584: {


1591:   if (x->mapping) {
1592:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1593:   }

1595:   if (x->ops->setlocaltoglobalmapping) {
1596:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1597:   } else {
1598:     x->mapping = mapping;
1599:     PetscObjectReference((PetscObject)mapping);
1600:   }
1601:   return(0);
1602: }

1606: /*@
1607:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1608:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1609:    using a local (per-processor) numbering.

1611:    Collective on Vec

1613:    Input Parameters:
1614: +  x - vector
1615: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

1617:    Notes: 
1618:    All vectors obtained with VecDuplicate() from this vector inherit the same mapping.

1620:    Level: intermediate

1622:    Concepts: vector^setting values blocked with local numbering

1624: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1625:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1626: @*/
1627: PetscErrorCode VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1628: {


1635:   if (x->bmapping) {
1636:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1637:   }
1638:   x->bmapping = mapping;
1639:   PetscObjectReference((PetscObject)mapping);
1640:   return(0);
1641: }

1645: /*@
1646:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1647:    using a local ordering of the nodes. 

1649:    Not Collective

1651:    Input Parameters:
1652: +  x - vector to insert in
1653: .  ni - number of elements to add
1654: .  ix - indices where to add
1655: .  y - array of values
1656: -  iora - either INSERT_VALUES or ADD_VALUES, where
1657:    ADD_VALUES adds values to any existing entries, and
1658:    INSERT_VALUES replaces existing entries with new values

1660:    Level: intermediate

1662:    Notes: 
1663:    VecSetValuesLocal() sets x[ix[i]] = y[i], for i=0,...,ni-1.

1665:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1666:    options cannot be mixed without intervening calls to the assembly
1667:    routines.

1669:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
1670:    MUST be called after all calls to VecSetValuesLocal() have been completed.

1672:    VecSetValuesLocal() uses 0-based indices in Fortran as well as in C.

1674:    Concepts: vector^setting values with local numbering

1676: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1677:            VecSetValuesBlockedLocal()
1678: @*/
1679: PetscErrorCode VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1680: {
1682:   PetscInt       lixp[128],*lix = lixp;


1690:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1691:   if (!x->ops->setvalueslocal) {
1692:     if (!x->mapping) {
1693:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1694:     }
1695:     if (ni > 128) {
1696:       PetscMalloc(ni*sizeof(PetscInt),&lix);
1697:     }
1698:     ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
1699:     (*x->ops->setvalues)(x,ni,lix,y,iora);
1700:     if (ni > 128) {
1701:       PetscFree(lix);
1702:     }
1703:   } else {
1704:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1705:   }
1706:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1707:   PetscObjectIncreaseState((PetscObject)x);
1708:   return(0);
1709: }

1713: /*@
1714:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1715:    using a local ordering of the nodes. 

1717:    Not Collective

1719:    Input Parameters:
1720: +  x - vector to insert in
1721: .  ni - number of blocks to add
1722: .  ix - indices where to add in block count, not element count
1723: .  y - array of values
1724: -  iora - either INSERT_VALUES or ADD_VALUES, where
1725:    ADD_VALUES adds values to any existing entries, and
1726:    INSERT_VALUES replaces existing entries with new values

1728:    Level: intermediate

1730:    Notes: 
1731:    VecSetValuesBlockedLocal() sets x[bs*ix[i]+j] = y[bs*i+j], 
1732:    for j=0,..bs-1, for i=0,...,ni-1, where bs has been set with VecSetBlockSize().

1734:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1735:    options cannot be mixed without intervening calls to the assembly
1736:    routines.

1738:    These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 
1739:    MUST be called after all calls to VecSetValuesBlockedLocal() have been completed.

1741:    VecSetValuesBlockedLocal() uses 0-based indices in Fortran as well as in C.


1744:    Concepts: vector^setting values blocked with local numbering

1746: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
1747:            VecSetLocalToGlobalMappingBlocked()
1748: @*/
1749: PetscErrorCode VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1750: {
1752:   PetscInt       lixp[128],*lix = lixp;

1759:   if (!x->bmapping) {
1760:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1761:   }
1762:   if (ni > 128) {
1763:     PetscMalloc(ni*sizeof(PetscInt),&lix);
1764:   }

1766:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1767:   ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
1768:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1769:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1770:   if (ni > 128) {
1771:     PetscFree(lix);
1772:   }
1773:   PetscObjectIncreaseState((PetscObject)x);
1774:   return(0);
1775: }

1779: /*@
1780:    VecAssemblyBegin - Begins assembling the vector.  This routine should
1781:    be called after completing all calls to VecSetValues().

1783:    Collective on Vec

1785:    Input Parameter:
1786: .  vec - the vector

1788:    Level: beginner

1790:    Concepts: assembly^vectors

1792: .seealso: VecAssemblyEnd(), VecSetValues()
1793: @*/
1794: PetscErrorCode VecAssemblyBegin(Vec vec)
1795: {
1797:   PetscTruth     flg;


1803:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1804:   if (flg) {
1805:     VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1806:   }

1808:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1809:   if (vec->ops->assemblybegin) {
1810:     (*vec->ops->assemblybegin)(vec);
1811:   }
1812:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1813:   PetscObjectIncreaseState((PetscObject)vec);
1814:   return(0);
1815: }

1819: /*@
1820:    VecAssemblyEnd - Completes assembling the vector.  This routine should
1821:    be called after VecAssemblyBegin().

1823:    Collective on Vec

1825:    Input Parameter:
1826: .  vec - the vector

1828:    Options Database Keys:
1829: +  -vec_view - Prints vector in ASCII format
1830: .  -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
1831: .  -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
1832: .  -vec_view_draw - Activates vector viewing using drawing tools
1833: .  -display <name> - Sets display name (default is host)
1834: .  -draw_pause <sec> - Sets number of seconds to pause after display
1835: -  -vec_view_socket - Activates vector viewing using a socket
1836:  
1837:    Level: beginner

1839: .seealso: VecAssemblyBegin(), VecSetValues()
1840: @*/
1841: PetscErrorCode VecAssemblyEnd(Vec vec)
1842: {
1844:   PetscTruth     flg;

1848:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
1850:   if (vec->ops->assemblyend) {
1851:     (*vec->ops->assemblyend)(vec);
1852:   }
1853:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
1854:   PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
1855:     PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
1856:     if (flg) {
1857:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1858:     }
1859:     PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
1860:     if (flg) {
1861:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
1862:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1863:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
1864:     }
1865: #if defined(PETSC_HAVE_MATLAB) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
1866:     PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
1867:     if (flg) {
1868:       VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
1869:     }
1870: #endif
1871:     PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
1872:     if (flg) {
1873:       VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
1874:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
1875:     }
1876:     PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
1877:     if (flg) {
1878:       VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
1879:       PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
1880:     }
1881:   PetscOptionsEnd();
1882:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
1883:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
1884:   PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
1885:   if (flg) {
1886:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1887:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1888:   }
1889:   PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
1890:   if (flg) {
1891:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
1892:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1893:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1894:   }
1895:   return(0);
1896: }


1901: /*@C
1902:    VecMTDot - Computes indefinite vector multiple dot products. 
1903:    That is, it does NOT use the complex conjugate.

1905:    Collective on Vec

1907:    Input Parameters:
1908: +  nv - number of vectors
1909: .  x - one vector
1910: -  y - array of vectors.  Note that vectors are pointers

1912:    Output Parameter:
1913: .  val - array of the dot products

1915:    Notes for Users of Complex Numbers:
1916:    For complex vectors, VecMTDot() computes the indefinite form
1917: $      val = (x,y) = y^T x,
1918:    where y^T denotes the transpose of y.

1920:    Use VecMDot() for the inner product
1921: $      val = (x,y) = y^H x,
1922:    where y^H denotes the conjugate transpose of y.

1924:    Level: intermediate

1926:    Concepts: inner product^multiple
1927:    Concepts: vector^multiple inner products

1929: .seealso: VecMDot(), VecTDot()
1930: @*/
1931: PetscErrorCode VecMTDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
1932: {

1943:   if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1944:   if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1946:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1947:   (*x->ops->mtdot)(nv,x,y,val);
1948:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1949:   return(0);
1950: }

1954: /*@C
1955:    VecMDot - Computes vector multiple dot products. 

1957:    Collective on Vec

1959:    Input Parameters:
1960: +  nv - number of vectors
1961: .  x - one vector
1962: -  y - array of vectors. 

1964:    Output Parameter:
1965: .  val - array of the dot products

1967:    Notes for Users of Complex Numbers:
1968:    For complex vectors, VecMDot() computes 
1969: $     val = (x,y) = y^H x,
1970:    where y^H denotes the conjugate transpose of y.

1972:    Use VecMTDot() for the indefinite form
1973: $     val = (x,y) = y^T x,
1974:    where y^T denotes the transpose of y.

1976:    Level: intermediate

1978:    Concepts: inner product^multiple
1979:    Concepts: vector^multiple inner products

1981: .seealso: VecMTDot(), VecDot()
1982: @*/
1983: PetscErrorCode VecMDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
1984: {

1995:   if (x->N != (*y)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1996:   if (x->n != (*y)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

1998:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1999:   (*x->ops->mdot)(nv,x,y,val);
2000:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
2001:   return(0);
2002: }

2006: /*@C
2007:    VecMAXPY - Computes y = y + sum alpha[j] x[j]

2009:    Collective on Vec

2011:    Input Parameters:
2012: +  nv - number of scalars and x-vectors
2013: .  alpha - array of scalars
2014: .  y - one vector
2015: -  x - array of vectors

2017:    Level: intermediate

2019:    Concepts: BLAS

2021: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2022: @*/
2023: PetscErrorCode  VecMAXPY(PetscInt nv,const PetscScalar *alpha,Vec y,Vec *x)
2024: {

2035:   if (y->N != (*x)->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
2036:   if (y->n != (*x)->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

2038:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2039:   (*y->ops->maxpy)(nv,alpha,y,x);
2040:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2041:   PetscObjectIncreaseState((PetscObject)y);
2042:   return(0);
2043: }

2045: /*MC
2046:    VecGetArray - Returns a pointer to a contiguous array that contains this 
2047:    processor's portion of the vector data. For the standard PETSc
2048:    vectors, VecGetArray() returns a pointer to the local data array and
2049:    does not use any copies. If the underlying vector data is not stored
2050:    in a contiquous array this routine will copy the data to a contiquous
2051:    array and return a pointer to that. You MUST call VecRestoreArray() 
2052:    when you no longer need access to the array.

2054:    Synopsis:
2055:    PetscErrorCode VecGetArray(Vec x,PetscScalar *a)

2057:    Not Collective

2059:    Input Parameter:
2060: .  x - the vector

2062:    Output Parameter:
2063: .  a - location to put pointer to the array

2065:    Fortran Note:
2066:    This routine is used differently from Fortran 77
2067: $    Vec         x
2068: $    PetscScalar x_array(1)
2069: $    PetscOffset i_x
2070: $    PetscErrorCode ierr
2071: $       call VecGetArray(x,x_array,i_x,ierr)
2072: $
2073: $   Access first local entry in vector with
2074: $      value = x_array(i_x + 1)
2075: $
2076: $      ...... other code
2077: $       call VecRestoreArray(x,x_array,i_x,ierr)
2078:    For Fortran 90 see VecGetArrayF90()

2080:    See the Fortran chapter of the users manual and 
2081:    petsc/src/snes/examples/tutorials/ex5f.F for details.

2083:    Level: beginner

2085:    Concepts: vector^accessing local values

2087: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2088: M*/
2091: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
2092: {

2099:   (*x->ops->getarray)(x,a);
2100:   return(0);
2101: }


2106: /*@C
2107:    VecGetArrays - Returns a pointer to the arrays in a set of vectors
2108:    that were created by a call to VecDuplicateVecs().  You MUST call
2109:    VecRestoreArrays() when you no longer need access to the array.

2111:    Not Collective

2113:    Input Parameter:
2114: +  x - the vectors
2115: -  n - the number of vectors

2117:    Output Parameter:
2118: .  a - location to put pointer to the array

2120:    Fortran Note:
2121:    This routine is not supported in Fortran.

2123:    Level: intermediate

2125: .seealso: VecGetArray(), VecRestoreArrays()
2126: @*/
2127: PetscErrorCode VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2128: {
2130:   PetscInt       i;
2131:   PetscScalar    **q;

2137:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
2138:   PetscMalloc(n*sizeof(PetscScalar*),&q);
2139:   for (i=0; i<n; ++i) {
2140:     VecGetArray(x[i],&q[i]);
2141:   }
2142:   *a = q;
2143:   return(0);
2144: }

2148: /*@C
2149:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2150:    has been called.

2152:    Not Collective

2154:    Input Parameters:
2155: +  x - the vector
2156: .  n - the number of vectors
2157: -  a - location of pointer to arrays obtained from VecGetArrays()

2159:    Notes:
2160:    For regular PETSc vectors this routine does not involve any copies. For
2161:    any special vectors that do not store local vector data in a contiguous
2162:    array, this routine will copy the data back into the underlying 
2163:    vector data structure from the arrays obtained with VecGetArrays().

2165:    Fortran Note:
2166:    This routine is not supported in Fortran.

2168:    Level: intermediate

2170: .seealso: VecGetArrays(), VecRestoreArray()
2171: @*/
2172: PetscErrorCode VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2173: {
2175:   PetscInt       i;
2176:   PetscScalar    **q = *a;


2183:   for(i=0;i<n;++i) {
2184:     VecRestoreArray(x[i],&q[i]);
2185:  }
2186:   PetscFree(q);
2187:   return(0);
2188: }

2190: /*MC
2191:    VecRestoreArray - Restores a vector after VecGetArray() has been called.

2193:    Not Collective

2195:    Synopsis:
2196:    PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a)

2198:    Input Parameters:
2199: +  x - the vector
2200: -  a - location of pointer to array obtained from VecGetArray()

2202:    Level: beginner

2204:    Notes:
2205:    For regular PETSc vectors this routine does not involve any copies. For
2206:    any special vectors that do not store local vector data in a contiguous
2207:    array, this routine will copy the data back into the underlying 
2208:    vector data structure from the array obtained with VecGetArray().

2210:    This routine actually zeros out the a pointer. This is to prevent accidental
2211:    us of the array after it has been restored. If you pass null for a it will 
2212:    not zero the array pointer a.

2214:    Fortran Note:
2215:    This routine is used differently from Fortran 77
2216: $    Vec         x
2217: $    PetscScalar x_array(1)
2218: $    PetscOffset i_x
2219: $    PetscErrorCode ierr
2220: $       call VecGetArray(x,x_array,i_x,ierr)
2221: $
2222: $   Access first local entry in vector with
2223: $      value = x_array(i_x + 1)
2224: $
2225: $      ...... other code
2226: $       call VecRestoreArray(x,x_array,i_x,ierr)

2228:    See the Fortran chapter of the users manual and 
2229:    petsc/src/snes/examples/tutorials/ex5f.F for details.
2230:    For Fortran 90 see VecRestoreArrayF90()

2232: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2233: M*/
2236: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
2237: {

2244: #if defined(PETSC_USE_BOPT_g)
2245:   CHKMEMQ;
2246: #endif
2247:   if (x->ops->restorearray) {
2248:     (*x->ops->restorearray)(x,a);
2249:   }
2250:   PetscObjectIncreaseState((PetscObject)x);
2251:   return(0);
2252: }

2254: #undef  __FUNCT__
2256: /*@
2257:   VecViewFromOptions - This function visualizes the vector based upon user options.

2259:   Collective on Vec

2261:   Input Parameters:
2262: . vec   - The vector
2263: . title - The title

2265:   Level: intermediate

2267: .keywords: Vec, view, options, database
2268: .seealso: VecSetFromOptions(), VecView()
2269: @*/
2270: PetscErrorCode VecViewFromOptions(Vec vec, char *title)
2271: {
2272:   PetscViewer    viewer;
2273:   PetscDraw      draw;
2274:   PetscTruth     opt;
2275:   char           *titleStr;
2276:   char           typeName[1024];
2277:   char           fileName[PETSC_MAX_PATH_LEN];
2278:   size_t         len;

2282:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2283:   if (opt == PETSC_TRUE) {
2284:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2285:     PetscStrlen(typeName, &len);
2286:     if (len > 0) {
2287:       PetscViewerCreate(vec->comm, &viewer);
2288:       PetscViewerSetType(viewer, typeName);
2289:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2290:       if (opt == PETSC_TRUE) {
2291:         PetscViewerSetFilename(viewer, fileName);
2292:       } else {
2293:         PetscViewerSetFilename(viewer, vec->name);
2294:       }
2295:       VecView(vec, viewer);
2296:       PetscViewerFlush(viewer);
2297:       PetscViewerDestroy(viewer);
2298:     } else {
2299:       VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2300:     }
2301:   }
2302:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2303:   if (opt == PETSC_TRUE) {
2304:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2305:     PetscViewerDrawGetDraw(viewer, 0, &draw);
2306:     if (title != PETSC_NULL) {
2307:       titleStr = title;
2308:     } else {
2309:       PetscObjectName((PetscObject) vec);
2310:       titleStr = vec->name;
2311:     }
2312:     PetscDrawSetTitle(draw, titleStr);
2313:     VecView(vec, viewer);
2314:     PetscViewerFlush(viewer);
2315:     PetscDrawPause(draw);
2316:     PetscViewerDestroy(viewer);
2317:   }
2318:   return(0);
2319: }

2323: /*@C
2324:    VecView - Views a vector object. 

2326:    Collective on Vec

2328:    Input Parameters:
2329: +  v - the vector
2330: -  viewer - an optional visualization context

2332:    Notes:
2333:    The available visualization contexts include
2334: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
2335: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2336:          output where only the first processor opens
2337:          the file.  All other processors send their 
2338:          data to the first processor to print. 

2340:    You can change the format the vector is printed using the 
2341:    option PetscViewerSetFormat().

2343:    The user can open alternative visualization contexts with
2344: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
2345: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
2346:          specified file; corresponding input uses VecLoad()
2347: .    PetscViewerDrawOpen() - Outputs vector to an X window display
2348: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

2350:    The user can call PetscViewerSetFormat() to specify the output
2351:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2352:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
2353: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2354: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2355: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2356: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
2357:          format common among all vector types

2359:    Level: beginner

2361:    Concepts: vector^printing
2362:    Concepts: vector^saving to disk

2364: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2365:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2366:           PetscRealView(), PetscScalarView(), PetscIntView()
2367: @*/
2368: PetscErrorCode VecView(Vec vec,PetscViewer viewer)
2369: {
2370:   PetscErrorCode    ierr;
2371:   PetscViewerFormat format;

2376:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(vec->comm);
2379:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

2381:   /*
2382:      Check if default viewer has been overridden, but user request it anyways
2383:   */
2384:   PetscViewerGetFormat(viewer,&format);
2385:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2386:     PetscViewerPopFormat(viewer);
2387:     (*vec->ops->viewnative)(vec,viewer);
2388:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2389:   } else {
2390:     (*vec->ops->view)(vec,viewer);
2391:   }
2392:   return(0);
2393: }

2397: /*@
2398:    VecGetSize - Returns the global number of elements of the vector.

2400:    Not Collective

2402:    Input Parameter:
2403: .  x - the vector

2405:    Output Parameters:
2406: .  size - the global length of the vector

2408:    Level: beginner

2410:    Concepts: vector^local size

2412: .seealso: VecGetLocalSize()
2413: @*/
2414: PetscErrorCode VecGetSize(Vec x,PetscInt *size)
2415: {

2422:   (*x->ops->getsize)(x,size);
2423:   return(0);
2424: }

2428: /*@
2429:    VecGetLocalSize - Returns the number of elements of the vector stored 
2430:    in local memory. This routine may be implementation dependent, so use 
2431:    with care.

2433:    Not Collective

2435:    Input Parameter:
2436: .  x - the vector

2438:    Output Parameter:
2439: .  size - the length of the local piece of the vector

2441:    Level: beginner

2443:    Concepts: vector^size

2445: .seealso: VecGetSize()
2446: @*/
2447: PetscErrorCode VecGetLocalSize(Vec x,PetscInt *size)
2448: {

2455:   (*x->ops->getlocalsize)(x,size);
2456:   return(0);
2457: }

2461: /*@C
2462:    VecGetOwnershipRange - Returns the range of indices owned by 
2463:    this processor, assuming that the vectors are laid out with the
2464:    first n1 elements on the first processor, next n2 elements on the
2465:    second, etc.  For certain parallel layouts this range may not be 
2466:    well defined. 

2468:    Not Collective

2470:    Input Parameter:
2471: .  x - the vector

2473:    Output Parameters:
2474: +  low - the first local element, pass in PETSC_NULL if not interested
2475: -  high - one more than the last local element, pass in PETSC_NULL if not interested

2477:    Note:
2478:    The high argument is one more than the last element stored locally.

2480:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

2482:    Level: beginner

2484:    Concepts: ownership^of vectors
2485:    Concepts: vector^ownership of elements

2487: @*/
2488: PetscErrorCode VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
2489: {

2497:   PetscMapGetLocalRange(x->map,low,high);
2498:   return(0);
2499: }

2503: /*@C
2504:    VecGetPetscMap - Returns the map associated with the vector

2506:    Not Collective

2508:    Input Parameter:
2509: .  x - the vector

2511:    Output Parameters:
2512: .  map - the map

2514:    Level: developer

2516: @*/
2517: PetscErrorCode VecGetPetscMap(Vec x,PetscMap *map)
2518: {
2523:   *map = x->map;
2524:   return(0);
2525: }

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

2532:    Collective on Vec

2534:    Input Parameter:
2535: +  x - the vector
2536: -  op - the option

2538:    Supported Options:
2539: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
2540:       entries destined to be stored on a seperate processor. This can be used
2541:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
2542:       that you have only used VecSetValues() to set local elements
2543: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

2545:    Level: intermediate

2547: @*/
2548: PetscErrorCode VecSetOption(Vec x,VecOption op)
2549: {

2555:   if (x->ops->setoption) {
2556:     (*x->ops->setoption)(x,op);
2557:   }
2558:   return(0);
2559: }

2563: /* Default routines for obtaining and releasing; */
2564: /* may be used by any implementation */
2565: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
2566: {
2568:   PetscInt       i;

2573:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2574:   PetscMalloc(m*sizeof(Vec*),V);
2575:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2576:   return(0);
2577: }

2581: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
2582: {
2584:   PetscInt       i;

2588:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2589:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
2590:   PetscFree(v);
2591:   return(0);
2592: }

2596: /*@
2597:    VecPlaceArray - Allows one to replace the array in a vector with an
2598:    array provided by the user. This is useful to avoid copying an array
2599:    into a vector.

2601:    Not Collective

2603:    Input Parameters:
2604: +  vec - the vector
2605: -  array - the array

2607:    Notes:
2608:    You can return to the original array with a call to VecResetArray()

2610:    Level: developer

2612: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecResetArray()

2614: @*/
2615: PetscErrorCode VecPlaceArray(Vec vec,const PetscScalar array[])
2616: {

2623:   if (vec->ops->placearray) {
2624:     (*vec->ops->placearray)(vec,array);
2625:   } else {
2626:     SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
2627:   }
2628:   PetscObjectIncreaseState((PetscObject)vec);
2629:   return(0);
2630: }

2634: /*@
2635:    VecResetArray - Resets a vector to use its default memory. Call this 
2636:    after the use of VecPlaceArray().

2638:    Not Collective

2640:    Input Parameters:
2641: .  vec - the vector

2643:    Level: developer

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

2647: @*/
2648: PetscErrorCode VecResetArray(Vec vec)
2649: {

2655:   if (vec->ops->resetarray) {
2656:     (*vec->ops->resetarray)(vec);
2657:   } else {
2658:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
2659:   }
2660:   PetscObjectIncreaseState((PetscObject)vec);
2661:   return(0);
2662: }

2666: /*@C
2667:    VecReplaceArray - Allows one to replace the array in a vector with an
2668:    array provided by the user. This is useful to avoid copying an array
2669:    into a vector.

2671:    Not Collective

2673:    Input Parameters:
2674: +  vec - the vector
2675: -  array - the array

2677:    Notes:
2678:    This permanently replaces the array and frees the memory associated
2679:    with the old array.

2681:    The memory passed in MUST be obtained with PetscMalloc() and CANNOT be
2682:    freed by the user. It will be freed when the vector is destroy. 

2684:    Not supported from Fortran

2686:    Level: developer

2688: .seealso: VecGetArray(), VecRestoreArray(), VecPlaceArray(), VecResetArray()

2690: @*/
2691: PetscErrorCode VecReplaceArray(Vec vec,const PetscScalar array[])
2692: {

2698:   if (vec->ops->replacearray) {
2699:     (*vec->ops->replacearray)(vec,array);
2700:  } else {
2701:     SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
2702:   }
2703:   PetscObjectIncreaseState((PetscObject)vec);
2704:   return(0);
2705: }

2707: /*MC
2708:     VecDuplicateVecsF90 - Creates several vectors of the same type as an existing vector
2709:     and makes them accessible via a Fortran90 pointer.

2711:     Synopsis:
2712:     VecDuplicateVecsF90(Vec x,int n,{Vec, pointer :: y(:)},integer ierr)

2714:     Collective on Vec

2716:     Input Parameters:
2717: +   x - a vector to mimic
2718: -   n - the number of vectors to obtain

2720:     Output Parameters:
2721: +   y - Fortran90 pointer to the array of vectors
2722: -   ierr - error code

2724:     Example of Usage: 
2725: .vb
2726:     Vec x
2727:     Vec, pointer :: y(:)
2728:     ....
2729:     call VecDuplicateVecsF90(x,2,y,ierr)
2730:     call VecSet(alpha,y(2),ierr)
2731:     call VecSet(alpha,y(2),ierr)
2732:     ....
2733:     call VecDestroyVecsF90(y,2,ierr)
2734: .ve

2736:     Notes:
2737:     Not yet supported for all F90 compilers

2739:     Use VecDestroyVecsF90() to free the space.

2741:     Level: beginner

2743: .seealso:  VecDestroyVecsF90(), VecDuplicateVecs()

2745: M*/

2747: /*MC
2748:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2749:     VecGetArrayF90().

2751:     Synopsis:
2752:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2754:     Not collective

2756:     Input Parameters:
2757: +   x - vector
2758: -   xx_v - the Fortran90 pointer to the array

2760:     Output Parameter:
2761: .   ierr - error code

2763:     Example of Usage: 
2764: .vb
2765:     PetscScalar, pointer :: xx_v(:)
2766:     ....
2767:     call VecGetArrayF90(x,xx_v,ierr)
2768:     a = xx_v(3)
2769:     call VecRestoreArrayF90(x,xx_v,ierr)
2770: .ve
2771:    
2772:     Notes:
2773:     Not yet supported for all F90 compilers

2775:     Level: beginner

2777: .seealso:  VecGetArrayF90(), VecGetArray(), VecRestoreArray()

2779: M*/

2781: /*MC
2782:     VecDestroyVecsF90 - Frees a block of vectors obtained with VecDuplicateVecsF90().

2784:     Synopsis:
2785:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

2787:     Input Parameters:
2788: +   x - pointer to array of vector pointers
2789: -   n - the number of vectors previously obtained

2791:     Output Parameter:
2792: .   ierr - error code

2794:     Notes:
2795:     Not yet supported for all F90 compilers

2797:     Level: beginner

2799: .seealso:  VecDestroyVecs(), VecDuplicateVecsF90()

2801: M*/

2803: /*MC
2804:     VecGetArrayF90 - Accesses a vector array from Fortran90. For default PETSc
2805:     vectors, VecGetArrayF90() returns a pointer to the local data array. Otherwise,
2806:     this routine is implementation dependent. You MUST call VecRestoreArrayF90() 
2807:     when you no longer need access to the array.

2809:     Synopsis:
2810:     VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2812:     Not Collective 

2814:     Input Parameter:
2815: .   x - vector

2817:     Output Parameters:
2818: +   xx_v - the Fortran90 pointer to the array
2819: -   ierr - error code

2821:     Example of Usage: 
2822: .vb
2823:     PetscScalar, pointer :: xx_v(:)
2824:     ....
2825:     call VecGetArrayF90(x,xx_v,ierr)
2826:     a = xx_v(3)
2827:     call VecRestoreArrayF90(x,xx_v,ierr)
2828: .ve

2830:     Notes:
2831:     Not yet supported for all F90 compilers

2833:     Level: beginner

2835: .seealso:  VecRestoreArrayF90(), VecGetArray(), VecRestoreArray()

2837: M*/

2841: /*@C 
2842:   VecLoadIntoVector - Loads a vector that has been stored in binary format
2843:   with VecView().

2845:   Collective on PetscViewer 

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

2851:   Level: intermediate

2853:   Notes:
2854:   The input file must contain the full global vector, as
2855:   written by the routine VecView().

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

2859:   Notes for advanced users:
2860:   Most users should not need to know the details of the binary storage
2861:   format, since VecLoad() and VecView() completely hide these details.
2862:   But for anyone who's interested, the standard binary matrix storage
2863:   format is
2864: .vb
2865:      int    VEC_FILE_COOKIE
2866:      int    number of rows
2867:      PetscScalar *values of all nonzeros
2868: .ve

2870:    Note for Cray users, the int's stored in the binary file are 32 bit
2871: integers; not 64 as they are represented in the memory, so if you
2872: write your own routines to read/write these binary files from the Cray
2873: you need to adjust the integer sizes that you read in, see
2874: PetscReadBinary() and PetscWriteBinary() to see how this may be
2875: done.

2877:    In addition, PETSc automatically does the byte swapping for
2878: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
2879: linux, Windows and the paragon; thus if you write your own binary
2880: read/write routines you have to swap the bytes; see PetscReadBinary()
2881: and PetscWriteBinary() to see how this may be done.

2883:    Concepts: vector^loading from file

2885: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
2886: @*/
2887: PetscErrorCode VecLoadIntoVector(PetscViewer viewer,Vec vec)
2888: {

2895:   if (!vec->ops->loadintovector) {
2896:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
2897:   }
2898:   (*vec->ops->loadintovector)(viewer,vec);
2899:   PetscObjectIncreaseState((PetscObject)vec);
2900:   return(0);
2901: }

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

2908:    Collective on Vec

2910:    Input Parameter:
2911: .  v - the vector 

2913:    Output Parameter:
2914: .  v - the vector reciprocal

2916:    Level: intermediate

2918:    Concepts: vector^reciprocal

2920: @*/
2921: PetscErrorCode VecReciprocal(Vec vec)
2922: {

2928:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
2929:   if (!vec->ops->reciprocal) {
2930:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
2931:   }
2932:   (*vec->ops->reciprocal)(vec);
2933:   PetscObjectIncreaseState((PetscObject)vec);
2934:   return(0);
2935: }

2939: PetscErrorCode VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2940: {
2943:   /* save the native version of the viewer */
2944:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
2945:     vec->ops->viewnative = vec->ops->view;
2946:   }
2947:   (((void(**)(void))vec->ops)[(int)op]) = f;
2948:   return(0);
2949: }

2953: /*@
2954:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
2955:    used during the assembly process to store values that belong to 
2956:    other processors.

2958:    Collective on Vec

2960:    Input Parameters:
2961: +  vec   - the vector
2962: .  size  - the initial size of the stash.
2963: -  bsize - the initial size of the block-stash(if used).

2965:    Options Database Keys:
2966: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2967: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

2969:    Level: intermediate

2971:    Notes: 
2972:      The block-stash is used for values set with VecSetValuesBlocked() while
2973:      the stash is used for values set with VecSetValues()

2975:      Run with the option -log_info and look for output of the form
2976:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2977:      to determine the appropriate value, MM, to use for size and 
2978:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2979:      to determine the value, BMM to use for bsize

2981:    Concepts: vector^stash
2982:    Concepts: stash^vector

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

2986: @*/
2987: PetscErrorCode VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
2988: {

2993:   VecStashSetInitialSize_Private(&vec->stash,size);
2994:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
2995:   return(0);
2996: }

3000: /*@
3001:    VecStashView - Prints the entries in the vector stash and block stash.

3003:    Collective on Vec

3005:    Input Parameters:
3006: +  vec   - the vector
3007: -  viewer - the viewer

3009:    Level: advanced

3011:    Concepts: vector^stash
3012:    Concepts: stash^vector

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

3016: @*/
3017: PetscErrorCode VecStashView(Vec v,PetscViewer viewer)
3018: {
3020:   PetscMPIInt    rank;
3021:   PetscInt       i,j;
3022:   PetscTruth     match;
3023:   VecStash       *s;
3024:   PetscScalar    val;


3031:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3032:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3033:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3034:   MPI_Comm_rank(v->comm,&rank);
3035:   s = &v->bstash;

3037:   /* print block stash */
3038:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
3039:   for (i=0; i<s->n; i++) {
3040:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
3041:     for (j=0; j<s->bs; j++) {
3042:       val = s->array[i*s->bs+j];
3043: #if defined(PETSC_USE_COMPLEX)
3044:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3045: #else
3046:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3047: #endif
3048:     }
3049:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3050:   }
3051:   PetscViewerFlush(viewer);

3053:   s = &v->stash;

3055:   /* print basic stash */
3056:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
3057:   for (i=0; i<s->n; i++) {
3058:     val = s->array[i];
3059: #if defined(PETSC_USE_COMPLEX)
3060:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3061: #else
3062:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
3063: #endif
3064:   }
3065:   PetscViewerFlush(viewer);

3067:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3068:   return(0);
3069: }

3073: /*@C
3074:    VecGetArray2d - Returns a pointer to a 2d contiguous array that contains this 
3075:    processor's portion of the vector data.  You MUST call VecRestoreArray2d() 
3076:    when you no longer need access to the array.

3078:    Not Collective

3080:    Input Parameter:
3081: +  x - the vector
3082: .  m - first dimension of two dimensional array
3083: .  n - second dimension of two dimensional array
3084: .  mstart - first index you will use in first coordinate direction (often 0)
3085: -  nstart - first index in the second coordinate direction (often 0)

3087:    Output Parameter:
3088: .  a - location to put pointer to the array

3090:    Level: beginner

3092:   Notes:
3093:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3094:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3095:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3096:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3097:    
3098:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3100:    Concepts: vector^accessing local values as 2d array

3102: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3103:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3104:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3105: @*/
3106: PetscErrorCode VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3107: {
3109:   PetscInt       i,N;
3110:   PetscScalar    *aa;

3116:   VecGetLocalSize(x,&N);
3117:   if (m*n != N) SETERRQ3(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 2d array dimensions %D by %D",N,m,n);
3118:   VecGetArray(x,&aa);

3120:   PetscMalloc(m*sizeof(PetscScalar*),a);
3121:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3122:   *a -= mstart;
3123:   return(0);
3124: }

3128: /*@C
3129:    VecRestoreArray2d - Restores a vector after VecGetArray2d() has been called.

3131:    Not Collective

3133:    Input Parameters:
3134: +  x - the vector
3135: .  m - first dimension of two dimensional array
3136: .  n - second dimension of the two dimensional array
3137: .  mstart - first index you will use in first coordinate direction (often 0)
3138: .  nstart - first index in the second coordinate direction (often 0)
3139: -  a - location of pointer to array obtained from VecGetArray2d()

3141:    Level: beginner

3143:    Notes:
3144:    For regular PETSc vectors this routine does not involve any copies. For
3145:    any special vectors that do not store local vector data in a contiguous
3146:    array, this routine will copy the data back into the underlying 
3147:    vector data structure from the array obtained with VecGetArray().

3149:    This routine actually zeros out the a pointer. 

3151: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3152:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3153:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3154: @*/
3155: PetscErrorCode VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3156: {
3158:   void           *dummy;

3164:   dummy = (void*)(*a + mstart);
3165:   PetscFree(dummy);
3166:   VecRestoreArray(x,PETSC_NULL);
3167:   return(0);
3168: }

3172: /*@C
3173:    VecGetArray1d - Returns a pointer to a 1d contiguous array that contains this 
3174:    processor's portion of the vector data.  You MUST call VecRestoreArray1d() 
3175:    when you no longer need access to the array.

3177:    Not Collective

3179:    Input Parameter:
3180: +  x - the vector
3181: .  m - first dimension of two dimensional array
3182: -  mstart - first index you will use in first coordinate direction (often 0)

3184:    Output Parameter:
3185: .  a - location to put pointer to the array

3187:    Level: beginner

3189:   Notes:
3190:    For a vector obtained from DACreateLocalVector() mstart are likely
3191:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3192:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
3193:    
3194:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3196: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3197:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3198:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3199: @*/
3200: PetscErrorCode VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3201: {
3203:   PetscInt       N;

3209:   VecGetLocalSize(x,&N);
3210:   if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
3211:   VecGetArray(x,a);
3212:   *a  -= mstart;
3213:   return(0);
3214: }

3218: /*@C
3219:    VecRestoreArray1d - Restores a vector after VecGetArray1d() has been called.

3221:    Not Collective

3223:    Input Parameters:
3224: +  x - the vector
3225: .  m - first dimension of two dimensional array
3226: .  mstart - first index you will use in first coordinate direction (often 0)
3227: -  a - location of pointer to array obtained from VecGetArray21()

3229:    Level: beginner

3231:    Notes:
3232:    For regular PETSc vectors this routine does not involve any copies. For
3233:    any special vectors that do not store local vector data in a contiguous
3234:    array, this routine will copy the data back into the underlying 
3235:    vector data structure from the array obtained with VecGetArray1d().

3237:    This routine actually zeros out the a pointer. 

3239:    Concepts: vector^accessing local values as 1d array

3241: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3242:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3243:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3244: @*/
3245: PetscErrorCode VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3246: {

3252:   VecRestoreArray(x,PETSC_NULL);
3253:   return(0);
3254: }

3258: /*@C
3259:    VecConjugate - Conjugates a vector.

3261:    Collective on Vec

3263:    Input Parameters:
3264: .  x - the vector

3266:    Level: intermediate

3268:    Concepts: vector^conjugate

3270: @*/
3271: PetscErrorCode VecConjugate(Vec x)
3272: {
3273: #ifdef PETSC_USE_COMPLEX

3279:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3280:   (*x->ops->conjugate)(x);
3281:   /* we need to copy norms here */
3282:   PetscObjectIncreaseState((PetscObject)x);
3283:   return(0);
3284: #else
3285:   return(0);
3286: #endif
3287: }

3291: /*@C
3292:    VecGetArray3d - Returns a pointer to a 3d contiguous array that contains this 
3293:    processor's portion of the vector data.  You MUST call VecRestoreArray3d() 
3294:    when you no longer need access to the array.

3296:    Not Collective

3298:    Input Parameter:
3299: +  x - the vector
3300: .  m - first dimension of three dimensional array
3301: .  n - second dimension of three dimensional array
3302: .  p - third dimension of three dimensional array
3303: .  mstart - first index you will use in first coordinate direction (often 0)
3304: .  nstart - first index in the second coordinate direction (often 0)
3305: -  pstart - first index in the third coordinate direction (often 0)

3307:    Output Parameter:
3308: .  a - location to put pointer to the array

3310:    Level: beginner

3312:   Notes:
3313:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3314:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3315:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3316:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3317:    
3318:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3320:    Concepts: vector^accessing local values as 3d array

3322: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3323:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3324:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3325: @*/
3326: PetscErrorCode VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3327: {
3329:   PetscInt       i,N,j;
3330:   PetscScalar    *aa,**b;

3336:   VecGetLocalSize(x,&N);
3337:   if (m*n*p != N) SETERRQ4(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 3d array dimensions %D by %D by %D",N,m,n,p);
3338:   VecGetArray(x,&aa);

3340:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3341:   b    = (PetscScalar **)((*a) + m);
3342:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
3343:   for (i=0; i<m; i++) {
3344:     for (j=0; j<n; j++) {
3345:       b[i*n+j] = aa + i*n*p + j*p - pstart;
3346:     }
3347:   }
3348:   *a -= mstart;
3349:   return(0);
3350: }

3354: /*@C
3355:    VecRestoreArray3d - Restores a vector after VecGetArray3d() has been called.

3357:    Not Collective

3359:    Input Parameters:
3360: +  x - the vector
3361: .  m - first dimension of three dimensional array
3362: .  n - second dimension of the three dimensional array
3363: .  p - third dimension of the three dimensional array
3364: .  mstart - first index you will use in first coordinate direction (often 0)
3365: .  nstart - first index in the second coordinate direction (often 0)
3366: .  pstart - first index in the third coordinate direction (often 0)
3367: -  a - location of pointer to array obtained from VecGetArray3d()

3369:    Level: beginner

3371:    Notes:
3372:    For regular PETSc vectors this routine does not involve any copies. For
3373:    any special vectors that do not store local vector data in a contiguous
3374:    array, this routine will copy the data back into the underlying 
3375:    vector data structure from the array obtained with VecGetArray().

3377:    This routine actually zeros out the a pointer. 

3379: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3380:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3381:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3382: @*/
3383: PetscErrorCode VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3384: {
3386:   void           *dummy;

3392:   dummy = (void*)(*a + mstart);
3393:   PetscFree(dummy);
3394:   VecRestoreArray(x,PETSC_NULL);
3395:   return(0);
3396: }

3398: EXTERN PetscErrorCode VecStashGetInfo_Private(VecStash*,PetscInt*,PetscInt*);
3401: /*@ 
3402:    VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
3403:        to be communicated to other processors during the VecAssemblyBegin/End() process

3405:     Not collective

3407:    Input Parameter:
3408: .   vec - the vector

3410:    Output Parameters:
3411: +   nstash   - the size of the stash
3412: .   reallocs - the number of additional mallocs incurred.
3413: .   bnstash   - the size of the block stash
3414: -   breallocs - the number of additional mallocs incurred.in the block stash
3415:  
3416:    Level: advanced

3418: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
3419:   
3420: @*/
3421: PetscErrorCode VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
3422: {
3425:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
3426:   VecStashGetInfo_Private(&vec->bstash,nstash,reallocs);
3427:   return(0);
3428: }