Actual source code: vector.c

  1: /*$Id: vector.c,v 1.238 2001/09/11 16:31:48 bsmith Exp $*/
  2: /*
  3:      Provides the interface functions for all vector operations.
  4:    These are the vector functions the user calls.
  5: */
 6:  #include vecimpl.h

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

 15: /* ugly globals for VecSetValue() and VecSetValueLocal() */
 16: int         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 int VecSetTypeFromOptions_Private(Vec vec)
 36: {
 37:   PetscTruth opt;
 38:   const char *defaultType;
 39:   char       typeName[256];
 40:   int        numProcs;
 41:   int        ierr;

 44:   if (vec->type_name != PETSC_NULL) {
 45:     defaultType = vec->type_name;
 46:   } else {
 47:     MPI_Comm_size(vec->comm, &numProcs);
 48:     if (numProcs > 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: 
 60:   if (opt == PETSC_TRUE) {
 61:     VecSetType(vec, typeName);
 62:   } else {
 63:     VecSetType(vec, defaultType);
 64:   }
 65:   return(0);
 66: }

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

 73:   Collective on Vec

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

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

 81:   Level: beginner

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

 86: .keywords: Vec, set, options, database
 87: .seealso: VecCreate(), VecPrintHelp(), VechSetOptionsPrefix()
 88: @*/
 89: int VecSetFromOptions(Vec vec)
 90: {
 91:   PetscTruth opt;
 92:   int        ierr;


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

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

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

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

114: #if defined(__cplusplus) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE) && defined(PETSC_HAVE_CXX_NAMESPACE)
115:   VecESISetFromOptions(vec);
116: #endif

118:   VecViewFromOptions(vec, vec->name);
119:   return(0);
120: }

124: /*@
125:   VecPrintHelp - Prints some options for the Vec.

127:   Input Parameter:
128: . vec - The vector

130:   Options Database Keys:
131: $  -help, -h

133:   Level: intermediate

135: .keywords: Vec, help
136: .seealso: VecSetFromOptions()
137: @*/
138: int VecPrintHelp(Vec vec)
139: {
142:   return(0);
143: }

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

150:   Collective on Vec

152:   Input Parameters:
153: + v - the vector
154: . n - the local size (or PETSC_DECIDE to have it set)
155: - N - the global size (or PETSC_DECIDE)

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

161:   Level: intermediate

163: .seealso: VecGetSize(), PetscSplitOwnership()
164: @*/
165: int VecSetSizes(Vec v, int n, int N)
166: {
169:   v->n = n;
170:   v->N = N;
171:   return(0);
172: }

176: /*@
177:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
178:    and VecSetValuesBlockedLocal().

180:    Collective on Vec

182:    Input Parameter:
183: +  v - the vector
184: -  bs - the blocksize

186:    Notes:
187:    All vectors obtained by VecDuplicate() inherit the same blocksize.

189:    Level: advanced

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

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

213: /*@
214:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
215:    and VecSetValuesBlockedLocal().

217:    Collective on Vec

219:    Input Parameter:
220: .  v - the vector

222:    Output Parameter:
223: .  bs - the blocksize

225:    Notes:
226:    All vectors obtained by VecDuplicate() inherit the same blocksize.

228:    Level: advanced

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

232:    Concepts: vector^block size
233:    Concepts: block^vector

235: @*/
236: int VecGetBlockSize(Vec v,int *bs)
237: {
241:   *bs = v->bs;
242:   return(0);
243: }

247: /*@
248:    VecValid - Checks whether a vector object is valid.

250:    Not Collective

252:    Input Parameter:
253: .  v - the object to check

255:    Output Parameter:
256:    flg - flag indicating vector status, either
257:    PETSC_TRUE if vector is valid, or PETSC_FALSE otherwise.

259:    Level: developer

261: @*/
262: int VecValid(Vec v,PetscTruth *flg)
263: {
266:   if (!v)                           *flg = PETSC_FALSE;
267:   else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
268:   else                              *flg = PETSC_TRUE;
269:   return(0);
270: }

274: /*@
275:    VecDot - Computes the vector dot product.

277:    Collective on Vec

279:    Input Parameters:
280: .  x, y - the vectors

282:    Output Parameter:
283: .  alpha - the dot product

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

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

296:    Use VecTDot() for the indefinite form
297: $     val = (x,y) = y^T x,
298:    where y^T denotes the transpose of y.

300:    Level: intermediate

302:    Concepts: inner product
303:    Concepts: vector^inner product

305: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
306: @*/
307: int VecDot(Vec x,Vec y,PetscScalar *val)
308: {

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

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

339: /*@
340:    VecNorm  - Computes the vector norm.

342:    Collective on Vec

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

350:    Output Parameter:
351: .  val - the norm 

353:    Notes:
354: $     NORM_1 denotes sum_i |x_i|
355: $     NORM_2 denotes sqrt(sum_i (x_i)^2)
356: $     NORM_INFINITY denotes max_i |x_i|

358:    Level: intermediate

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

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

371:    Concepts: norm
372:    Concepts: vector^norm

374: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), 
375:           VecNormBegin(), VecNormEnd()

377: @*/
378: int VecNorm(Vec x,NormType type,PetscReal *val)
379: {
380:   PetscTruth flg;
381:   int        type_id, ierr;


388:   /*
389:    * Cached data?
390:    */
391:   VecNormComposedDataID(type,&type_id);
392:   PetscObjectGetRealComposedData((PetscObject)x,type_id,*val,flg);
393:   if (flg) return(0);
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:     int 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: int VecNormComposedDataID(NormType type,int *type_id)
421: {
422:   static int id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
425:   switch (type) {
426:   case NORM_1 :
427:     if (id_norm1==-1) {
428:       PetscRegisterComposedData(&id_norm1); }
429:     *type_id = id_norm1; break;
430:   case NORM_2 :
431:     if (id_norm2==-1) {
432:       PetscRegisterComposedData(&id_norm2); }
433:     *type_id = id_norm2; break;
434:   case NORM_1_AND_2 :
435:     /* we don't handle this one yet */
436:     if (id_norm1==-1) {
437:       PetscRegisterComposedData(&id_norm1); }
438:     if (id_norm2==-1) {
439:       PetscRegisterComposedData(&id_norm2); }
440:     *type_id = id_norm12; break;
441:   case NORM_INFINITY :
442:     if (id_normInf==-1) {
443:       PetscRegisterComposedData(&id_normInf); }
444:     *type_id = id_normInf; break;
445:   case NORM_FROBENIUS :
446:     if (id_normF==-1) {
447:       PetscRegisterComposedData(&id_normF); }
448:     *type_id = id_normF; break;
449:   }
450:   return(0);
451: }

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

458:    Collective on Vec

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

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

467:    Level: intermediate

469:    Concepts: vector^normalizing
470:    Concepts: normalizing^vector

472: @*/
473: int VecNormalize (Vec x,PetscReal *val)
474: {

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

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

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

499:    Collective on Vec

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

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

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

511:    Level: intermediate

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

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

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

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

537:    Collective on Vec

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

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

546:    Level: intermediate

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

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

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

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

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

576:    Collective on Vec

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

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

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

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

593:    Level: intermediate

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

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

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

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

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

626:    Collective on Vec

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

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

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

639:    Level: intermediate

641:    Concepts: vector^scaling
642:    Concepts: scaling^vector

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

655:   PetscLogEventBegin(VEC_Scale,x,0,0,0);
656:   (*x->ops->scale)(alpha,x);

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

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

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

697:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
698:   return(0);
699: }

703: /*@
704:    VecCopy - Copies a vector. 

706:    Collective on Vec

708:    Input Parameter:
709: .  x - the vector

711:    Output Parameter:
712: .  y - the copy

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

718:    Level: beginner

720: .seealso: VecDuplicate()
721: @*/
722: int VecCopy(Vec x,Vec y)
723: {
724:   PetscTruth flg;
725:   PetscReal  norm=0.0;
726:   int        type_id,ierr;

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

737:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
738:   (*x->ops->copy)(x,y);

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

771:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
772:   return(0);
773: }

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

780:    Collective on Vec

782:    Input Parameters:
783: +  alpha - the scalar
784: -  x  - the vector

786:    Output Parameter:
787: .  x  - the vector

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

796:    Level: beginner

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

800:    Concepts: vector^setting to constant

802: @*/
803: int VecSet(const PetscScalar *alpha,Vec x)
804: {
805:   PetscReal  val;
806:   int        type_id,ierr;


813:   PetscLogEventBegin(VEC_Set,x,0,0,0);
814:   (*x->ops->set)(alpha,x);
815:   PetscLogEventEnd(VEC_Set,x,0,0,0);

817:   /*
818:    * Update cached data
819:    */
820:   /* in general we consider this object touched */
821:   PetscObjectIncreaseState((PetscObject)x);
822:   /* however, norms can be simply set */
823:   /* 1 */
824:   val = PetscAbsScalar(*alpha);
825:   VecNormComposedDataID(NORM_1,&type_id);
826:   PetscObjectSetRealComposedData((PetscObject)x,type_id,x->N * val);
827:   /* inf */
828:   VecNormComposedDataID(NORM_INFINITY,&type_id);
829:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
830:   /* 2 */
831:   val = sqrt((double)x->N) * val;
832:   VecNormComposedDataID(NORM_2,&type_id);
833:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);
834:   /* frobenius */
835:   VecNormComposedDataID(NORM_FROBENIUS,&type_id);
836:   PetscObjectSetRealComposedData((PetscObject)x,type_id,val);

838:   return(0);
839: }

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

846:    Collective on Vec

848:    Input Parameters:
849: +  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
850:           it will create one internally.
851: -  x  - the vector

853:    Output Parameter:
854: .  x  - the vector

856:    Example of Usage:
857: .vb
858:      PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
859:      VecSetRandom(rctx,x);
860:      PetscRandomDestroy(rctx);
861: .ve

863:    Level: intermediate

865:    Concepts: vector^setting to random
866:    Concepts: random^vector

868: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
869: @*/
870: int VecSetRandom(PetscRandom rctx,Vec x)
871: {
872:   int         ierr;
873:   PetscRandom randObj = PETSC_NULL;


880:   if (!rctx) {
881:     MPI_Comm    comm;
882:     PetscObjectGetComm((PetscObject)x,&comm);
883:     PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
884:     rctx = randObj;
885:   }

887:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
888:   (*x->ops->setrandom)(rctx,x);
889:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
890: 
891:   if (randObj) {
892:     PetscRandomDestroy(randObj);
893:   }
894:   PetscObjectIncreaseState((PetscObject)x);
895:   return(0);
896: }

900: /*@
901:    VecAXPY - Computes y = alpha x + y. 

903:    Collective on Vec

905:    Input Parameters:
906: +  alpha - the scalar
907: -  x, y  - the vectors

909:    Output Parameter:
910: .  y - output vector

912:    Level: intermediate

914:    Concepts: vector^BLAS
915:    Concepts: BLAS

917: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
918: @*/
919: int VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
920: {

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

933:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
934:   (*x->ops->axpy)(alpha,x,y);
935:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
936:   PetscObjectIncreaseState((PetscObject)y);
937:   return(0);
938: }

942: /*@
943:    VecAXPBY - Computes y = alpha x + beta y. 

945:    Collective on Vec

947:    Input Parameters:
948: +  alpha,beta - the scalars
949: -  x, y  - the vectors

951:    Output Parameter:
952: .  y - output vector

954:    Level: intermediate

956:    Concepts: BLAS
957:    Concepts: vector^BLAS

959: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
960: @*/
961: int VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
962: {

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

976:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
977:   (*x->ops->axpby)(alpha,beta,x,y);
978:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
979:   PetscObjectIncreaseState((PetscObject)y);
980:   return(0);
981: }

985: /*@
986:    VecAYPX - Computes y = x + alpha y.

988:    Collective on Vec

990:    Input Parameters:
991: +  alpha - the scalar
992: -  x, y  - the vectors

994:    Output Parameter:
995: .  y - output vector

997:    Level: intermediate

999:    Concepts: vector^BLAS
1000:    Concepts: BLAS

1002: .seealso: VecAXPY(), VecWAXPY()
1003: @*/
1004: int VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
1005: {

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

1018:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1019:    (*x->ops->aypx)(alpha,x,y);
1020:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1021:   PetscObjectIncreaseState((PetscObject)y);
1022:   return(0);
1023: }

1027: /*@
1028:    VecSwap - Swaps the vectors x and y.

1030:    Collective on Vec

1032:    Input Parameters:
1033: .  x, y  - the vectors

1035:    Level: advanced

1037:    Concepts: vector^swapping values

1039: @*/
1040: int VecSwap(Vec x,Vec y)
1041: {
1042:   PetscReal  norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1043:   PetscReal  norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1044:   PetscTruth flg1x,flg2x,flgInfx,flgFx;
1045:   PetscTruth flg1y,flg2y,flgInfy,flgFy;
1046:   int        type_id1,type_id2,type_idInf,type_idF;
1047:   int        ierr;

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

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

1060:   /* See if we have cached norms */
1061:   /* 1 */
1062:   VecNormComposedDataID(NORM_1,&type_id1);
1063:   PetscObjectGetRealComposedData((PetscObject)x,type_id1,norm1x,flg1x);
1064:   PetscObjectGetRealComposedData((PetscObject)y,type_id1,norm1y,flg1y);
1065:   /* 2 */
1066:   VecNormComposedDataID(NORM_2,&type_id2);
1067:   PetscObjectGetRealComposedData((PetscObject)x,type_id2,norm2x,flg2x);
1068:   PetscObjectGetRealComposedData((PetscObject)y,type_id2,norm2y,flg2y);
1069:   /* inf */
1070:   VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1071:   PetscObjectGetRealComposedData((PetscObject)x,type_idInf,normInfx,flgInfx);
1072:   PetscObjectGetRealComposedData((PetscObject)y,type_idInf,normInfy,flgInfy);
1073:   /* frobenius */
1074:   VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1075:   PetscObjectGetRealComposedData((PetscObject)x,type_idF,normFx,flgFx);
1076:   PetscObjectGetRealComposedData((PetscObject)y,type_idF,normFy,flgFy);

1078:   /* Do the actual swap */
1079:   (*x->ops->swap)(x,y);
1080:   PetscObjectIncreaseState((PetscObject)x);
1081:   PetscObjectIncreaseState((PetscObject)y);

1083:   /* Swap any cached norms */
1084:   /* 1 */
1085:   if (flg1x) {
1086:     PetscObjectSetRealComposedData((PetscObject)y,type_id1,norm1x);
1087:   }
1088:   if (flg1y) {
1089:     PetscObjectSetRealComposedData((PetscObject)x,type_id1,norm1y);
1090:   }
1091:   /* 2 */
1092:   if (flg2x) {
1093:     PetscObjectSetRealComposedData((PetscObject)y,type_id2,norm2x);
1094:   }
1095:   if (flg2y) {
1096:     PetscObjectSetRealComposedData((PetscObject)x,type_id2,norm2y);
1097:   }
1098:   /* inf */
1099:   if (flgInfx) {
1100:     PetscObjectSetRealComposedData((PetscObject)y,type_idInf,normInfx);
1101:   }
1102:   if (flgInfy) {
1103:     PetscObjectSetRealComposedData((PetscObject)x,type_idInf,normInfy);
1104:   }
1105:   /* frobenius */
1106:   if (flgFx) {
1107:     PetscObjectSetRealComposedData((PetscObject)y,type_idF,normFx);
1108:   }
1109:   if (flgFy) {
1110:     PetscObjectSetRealComposedData((PetscObject)x,type_idF,normFy);
1111:   }

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

1115:   return(0);
1116: }

1120: /*@
1121:    VecWAXPY - Computes w = alpha x + y.

1123:    Collective on Vec

1125:    Input Parameters:
1126: +  alpha - the scalar
1127: -  x, y  - the vectors

1129:    Output Parameter:
1130: .  w - the result

1132:    Level: intermediate

1134:    Concepts: vector^BLAS
1135:    Concepts: BLAS

1137: .seealso: VecAXPY(), VecAYPX()
1138: @*/
1139: int VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
1140: {

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

1156:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1157:    (*x->ops->waxpy)(alpha,x,y,w);
1158:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1159:   PetscObjectIncreaseState((PetscObject)w);
1160:   return(0);
1161: }

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

1168:    Collective on Vec

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

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

1176:    Level: advanced

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

1180:    Concepts: vector^pointwise multiply

1182: .seealso: VecPointwiseDivide()
1183: @*/
1184: int VecPointwiseMult(Vec x,Vec y,Vec w)
1185: {

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

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

1209: /*@
1210:    VecPointwiseDivide - Computes the componentwise division w = x/y.

1212:    Collective on Vec

1214:    Input Parameters:
1215: .  x, y  - the vectors

1217:    Output Parameter:
1218: .  w - the result

1220:    Level: advanced

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

1224:    Concepts: vector^pointwise divide

1226: .seealso: VecPointwiseMult()
1227: @*/
1228: int VecPointwiseDivide(Vec x,Vec y,Vec w)
1229: {

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

1244:   (*x->ops->pointwisedivide)(x,y,w);
1245:   PetscObjectIncreaseState((PetscObject)w);
1246:   return(0);
1247: }

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

1254:    Collective on Vec

1256:    Input Parameters:
1257: .  x, y  - the vectors

1259:    Output Parameter:
1260: .  max - the result

1262:    Level: advanced

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

1266: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1267: @*/
1268: int VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1269: {

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

1282:   (*x->ops->maxpointwisedivide)(x,y,max);
1283:   return(0);
1284: }

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

1291:    Collective on Vec

1293:    Input Parameters:
1294: .  v - a vector to mimic

1296:    Output Parameter:
1297: .  newv - location to put new vector

1299:    Notes:
1300:    VecDuplicate() does not copy the vector, but rather allocates storage
1301:    for the new vector.  Use VecCopy() to copy a vector.

1303:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1304:    vectors. 

1306:    Level: beginner

1308: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1309: @*/
1310: int VecDuplicate(Vec x,Vec *newv)
1311: {

1318:   (*x->ops->duplicate)(x,newv);
1319:   PetscObjectIncreaseState((PetscObject)*newv);
1320:   return(0);
1321: }

1325: /*@C
1326:    VecDestroy - Destroys a vector.

1328:    Collective on Vec

1330:    Input Parameters:
1331: .  v  - the vector

1333:    Level: beginner

1335: .seealso: VecDuplicate(), VecDestroyVecs()
1336: @*/
1337: int VecDestroy(Vec v)
1338: {

1343:   if (--v->refct > 0) return(0);
1344:   /* destroy the internal part */
1345:   if (v->ops->destroy) {
1346:     (*v->ops->destroy)(v);
1347:   }
1348:   /* destroy the external/common part */
1349:   if (v->mapping) {
1350:     ISLocalToGlobalMappingDestroy(v->mapping);
1351:   }
1352:   if (v->bmapping) {
1353:     ISLocalToGlobalMappingDestroy(v->bmapping);
1354:   }
1355:   if (v->map) {
1356:     PetscMapDestroy(v->map);
1357:   }
1358:   PetscLogObjectDestroy(v);
1359:   PetscHeaderDestroy(v);
1360:   return(0);
1361: }

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

1368:    Collective on Vec

1370:    Input Parameters:
1371: +  m - the number of vectors to obtain
1372: -  v - a vector to mimic

1374:    Output Parameter:
1375: .  V - location to put pointer to array of vectors

1377:    Notes:
1378:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1379:    vector.

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

1386:    Level: intermediate

1388: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1389: @*/
1390: int VecDuplicateVecs(Vec v,int m,Vec *V[])
1391: {

1398:   (*v->ops->duplicatevecs)(v, m,V);
1399:   return(0);
1400: }

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

1407:    Collective on Vec

1409:    Input Parameters:
1410: +  vv - pointer to array of vector pointers
1411: -  m - the number of vectors previously obtained

1413:    Fortran Note:
1414:    The Fortran interface is slightly different from that given below.
1415:    See the Fortran chapter of the users manual and 
1416:    petsc/src/vec/examples for details.

1418:    Level: intermediate

1420: .seealso: VecDuplicateVecs(), VecDestroyVecsF90()
1421: @*/
1422: int VecDestroyVecs(const Vec vv[],int m)
1423: {

1430:   (*(*vv)->ops->destroyvecs)(vv,m);
1431:   return(0);
1432: }


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

1440:    Input Parameters:
1441:    Not Collective

1443: +  x - vector to insert in
1444: .  ni - number of elements to add
1445: .  ix - indices where to add
1446: .  y - array of values
1447: -  iora - either INSERT_VALUES or ADD_VALUES, where
1448:    ADD_VALUES adds values to any existing entries, and
1449:    INSERT_VALUES replaces existing entries with new values

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

1454:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1455:    options cannot be mixed without intervening calls to the assembly
1456:    routines.

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

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

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

1468:    Level: beginner

1470:    Concepts: vector^setting values

1472: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1473:            VecSetValue(), VecSetValuesBlocked()
1474: @*/
1475: int VecSetValues(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1476: {

1484:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1485:   (*x->ops->setvalues)(x,ni,ix,y,iora);
1486:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1487:   PetscObjectIncreaseState((PetscObject)x);
1488:   return(0);
1489: }

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

1496:    Not Collective

1498:    Input Parameters:
1499: +  x - vector to insert in
1500: .  ni - number of blocks to add
1501: .  ix - indices where to add in block count, rather than element count
1502: .  y - array of values
1503: -  iora - either INSERT_VALUES or ADD_VALUES, where
1504:    ADD_VALUES adds values to any existing entries, and
1505:    INSERT_VALUES replaces existing entries with new values

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

1511:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
1512:    options cannot be mixed without intervening calls to the assembly
1513:    routines.

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

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

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

1525:    Level: intermediate

1527:    Concepts: vector^setting values blocked

1529: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1530:            VecSetValues()
1531: @*/
1532: int VecSetValuesBlocked(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1533: {

1541:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1542:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1543:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1544:   PetscObjectIncreaseState((PetscObject)x);
1545:   return(0);
1546: }

1550: /*@
1551:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1552:    by the routine VecSetValuesLocal() to allow users to insert vector entries
1553:    using a local (per-processor) numbering.

1555:    Collective on Vec

1557:    Input Parameters:
1558: +  x - vector
1559: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1564:    Level: intermediate

1566:    Concepts: vector^setting values with local numbering

1568: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1569:            VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1570: @*/
1571: int VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1572: {

1578:   if (x->mapping) {
1579:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1580:   }

1582:   if (x->ops->setlocaltoglobalmapping) {
1583:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1584:   } else {
1585:     x->mapping = mapping;
1586:     PetscObjectReference((PetscObject)mapping);
1587:   }
1588:   return(0);
1589: }

1593: /*@
1594:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1595:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1596:    using a local (per-processor) numbering.

1598:    Collective on Vec

1600:    Input Parameters:
1601: +  x - vector
1602: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1607:    Level: intermediate

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

1611: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1612:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1613: @*/
1614: int VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1615: {

1621:   if (x->bmapping) {
1622:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1623:   }
1624:   x->bmapping = mapping;
1625:   PetscObjectReference((PetscObject)mapping);
1626:   return(0);
1627: }

1631: /*@
1632:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1633:    using a local ordering of the nodes. 

1635:    Not Collective

1637:    Input Parameters:
1638: +  x - vector to insert in
1639: .  ni - number of elements to add
1640: .  ix - indices where to add
1641: .  y - array of values
1642: -  iora - either INSERT_VALUES or ADD_VALUES, where
1643:    ADD_VALUES adds values to any existing entries, and
1644:    INSERT_VALUES replaces existing entries with new values

1646:    Level: intermediate

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

1651:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1652:    options cannot be mixed without intervening calls to the assembly
1653:    routines.

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

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

1660:    Concepts: vector^setting values with local numbering

1662: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1663:            VecSetValuesBlockedLocal()
1664: @*/
1665: int VecSetValuesLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1666: {
1667:   int ierr,lixp[128],*lix = lixp;


1675:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1676:   if (!x->ops->setvalueslocal) {
1677:     if (!x->mapping) {
1678:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1679:     }
1680:     if (ni > 128) {
1681:       PetscMalloc(ni*sizeof(int),&lix);
1682:     }
1683:     ISLocalToGlobalMappingApply(x->mapping,ni,(int*)ix,lix);
1684:     (*x->ops->setvalues)(x,ni,lix,y,iora);
1685:     if (ni > 128) {
1686:       PetscFree(lix);
1687:     }
1688:   } else {
1689:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1690:   }
1691:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1692:   PetscObjectIncreaseState((PetscObject)x);
1693:   return(0);
1694: }

1698: /*@
1699:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1700:    using a local ordering of the nodes. 

1702:    Not Collective

1704:    Input Parameters:
1705: +  x - vector to insert in
1706: .  ni - number of blocks to add
1707: .  ix - indices where to add in block count, not element count
1708: .  y - array of values
1709: -  iora - either INSERT_VALUES or ADD_VALUES, where
1710:    ADD_VALUES adds values to any existing entries, and
1711:    INSERT_VALUES replaces existing entries with new values

1713:    Level: intermediate

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

1719:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1720:    options cannot be mixed without intervening calls to the assembly
1721:    routines.

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

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


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

1731: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
1732:            VecSetLocalToGlobalMappingBlocked()
1733: @*/
1734: int VecSetValuesBlockedLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1735: {
1736:   int ierr,lixp[128],*lix = lixp;

1743:   if (!x->bmapping) {
1744:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1745:   }
1746:   if (ni > 128) {
1747:     PetscMalloc(ni*sizeof(int),&lix);
1748:   }

1750:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1751:   ISLocalToGlobalMappingApply(x->bmapping,ni,(int*)ix,lix);
1752:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1753:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1754:   if (ni > 128) {
1755:     PetscFree(lix);
1756:   }
1757:   PetscObjectIncreaseState((PetscObject)x);
1758:   return(0);
1759: }

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

1767:    Collective on Vec

1769:    Input Parameter:
1770: .  vec - the vector

1772:    Level: beginner

1774:    Concepts: assembly^vectors

1776: .seealso: VecAssemblyEnd(), VecSetValues()
1777: @*/
1778: int VecAssemblyBegin(Vec vec)
1779: {
1780:   int        ierr;
1781:   PetscTruth flg;


1787:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1788:   if (flg) {
1789:     VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1790:   }

1792:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1793:   if (vec->ops->assemblybegin) {
1794:     (*vec->ops->assemblybegin)(vec);
1795:   }
1796:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1797:   PetscObjectIncreaseState((PetscObject)vec);
1798:   return(0);
1799: }

1803: /*@
1804:    VecAssemblyEnd - Completes assembling the vector.  This routine should
1805:    be called after VecAssemblyBegin().

1807:    Collective on Vec

1809:    Input Parameter:
1810: .  vec - the vector

1812:    Options Database Keys:
1813: +  -vec_view - Prints vector in ASCII format
1814: .  -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
1815: .  -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
1816: .  -vec_view_draw - Activates vector viewing using drawing tools
1817: .  -display <name> - Sets display name (default is host)
1818: .  -draw_pause <sec> - Sets number of seconds to pause after display
1819: .  -vec_view_socket - Activates vector viewing using a socket
1820: -  -vec_view_ams - Activates vector viewing using the ALICE Memory Snooper (AMS)
1821:  
1822:    Level: beginner

1824: .seealso: VecAssemblyBegin(), VecSetValues()
1825: @*/
1826: int VecAssemblyEnd(Vec vec)
1827: {
1828:   int        ierr;
1829:   PetscTruth flg;

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


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

1896:    Collective on Vec

1898:    Input Parameters:
1899: +  nv - number of vectors
1900: .  x - one vector
1901: -  y - array of vectors.  Note that vectors are pointers

1903:    Output Parameter:
1904: .  val - array of the dot products

1906:    Notes for Users of Complex Numbers:
1907:    For complex vectors, VecMTDot() computes the indefinite form
1908: $      val = (x,y) = y^T x,
1909:    where y^T denotes the transpose of y.

1911:    Use VecMDot() for the inner product
1912: $      val = (x,y) = y^H x,
1913:    where y^H denotes the conjugate transpose of y.

1915:    Level: intermediate

1917:    Concepts: inner product^multiple
1918:    Concepts: vector^multiple inner products

1920: .seealso: VecMDot(), VecTDot()
1921: @*/
1922: int VecMTDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1923: {

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

1937:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1938:   (*x->ops->mtdot)(nv,x,y,val);
1939:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1940:   return(0);
1941: }

1945: /*@C
1946:    VecMDot - Computes vector multiple dot products. 

1948:    Collective on Vec

1950:    Input Parameters:
1951: +  nv - number of vectors
1952: .  x - one vector
1953: -  y - array of vectors. 

1955:    Output Parameter:
1956: .  val - array of the dot products

1958:    Notes for Users of Complex Numbers:
1959:    For complex vectors, VecMDot() computes 
1960: $     val = (x,y) = y^H x,
1961:    where y^H denotes the conjugate transpose of y.

1963:    Use VecMTDot() for the indefinite form
1964: $     val = (x,y) = y^T x,
1965:    where y^T denotes the transpose of y.

1967:    Level: intermediate

1969:    Concepts: inner product^multiple
1970:    Concepts: vector^multiple inner products

1972: .seealso: VecMTDot(), VecDot()
1973: @*/
1974: int VecMDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1975: {

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

1989:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1990:   (*x->ops->mdot)(nv,x,y,val);
1991:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
1992:   return(0);
1993: }

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

2000:    Collective on Vec

2002:    Input Parameters:
2003: +  nv - number of scalars and x-vectors
2004: .  alpha - array of scalars
2005: .  y - one vector
2006: -  x - array of vectors

2008:    Level: intermediate

2010:    Concepts: BLAS

2012: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2013: @*/
2014: int  VecMAXPY(int nv,const PetscScalar *alpha,Vec y,Vec *x)
2015: {

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

2029:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2030:   (*y->ops->maxpy)(nv,alpha,y,x);
2031:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2032:   PetscObjectIncreaseState((PetscObject)y);
2033:   return(0);
2034: }

2036: /*MC
2037:    VecGetArray - Returns a pointer to a contiguous array that contains this 
2038:    processor's portion of the vector data. For the standard PETSc
2039:    vectors, VecGetArray() returns a pointer to the local data array and
2040:    does not use any copies. If the underlying vector data is not stored
2041:    in a contiquous array this routine will copy the data to a contiquous
2042:    array and return a pointer to that. You MUST call VecRestoreArray() 
2043:    when you no longer need access to the array.

2045:    Not Collective

2047:    Input Parameter:
2048: .  x - the vector

2050:    Output Parameter:
2051: .  a - location to put pointer to the array

2053:    Fortran Note:
2054:    This routine is used differently from Fortran 77
2055: $    Vec         x
2056: $    PetscScalar x_array(1)
2057: $    PetscOffset i_x
2058: $    int         ierr
2059: $       call VecGetArray(x,x_array,i_x,ierr)
2060: $
2061: $   Access first local entry in vector with
2062: $      value = x_array(i_x + 1)
2063: $
2064: $      ...... other code
2065: $       call VecRestoreArray(x,x_array,i_x,ierr)
2066:    For Fortran 90 see VecGetArrayF90()

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

2071:    Level: beginner

2073:    Concepts: vector^accessing local values

2075: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2076: M*/
2079: int VecGetArray_Private(Vec x,PetscScalar *a[])
2080: {

2087:   (*x->ops->getarray)(x,a);
2088:   return(0);
2089: }


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

2099:    Not Collective

2101:    Input Parameter:
2102: +  x - the vectors
2103: -  n - the number of vectors

2105:    Output Parameter:
2106: .  a - location to put pointer to the array

2108:    Fortran Note:
2109:    This routine is not supported in Fortran.

2111:    Level: intermediate

2113: .seealso: VecGetArray(), VecRestoreArrays()
2114: @*/
2115: int VecGetArrays(const Vec x[],int n,PetscScalar **a[])
2116: {
2117:   int         i,ierr;
2118:   PetscScalar **q;

2124:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %d",n);
2125:   PetscMalloc(n*sizeof(PetscScalar*),&q);
2126:   for (i=0; i<n; ++i) {
2127:     VecGetArray(x[i],&q[i]);
2128:   }
2129:   *a = q;
2130:   return(0);
2131: }

2135: /*@C
2136:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2137:    has been called.

2139:    Not Collective

2141:    Input Parameters:
2142: +  x - the vector
2143: .  n - the number of vectors
2144: -  a - location of pointer to arrays obtained from VecGetArrays()

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

2152:    Fortran Note:
2153:    This routine is not supported in Fortran.

2155:    Level: intermediate

2157: .seealso: VecGetArrays(), VecRestoreArray()
2158: @*/
2159: int VecRestoreArrays(const Vec x[],int n,PetscScalar **a[])
2160: {
2161:   int         i,ierr;
2162:   PetscScalar **q = *a;


2169:   for(i=0;i<n;++i) {
2170:     VecRestoreArray(x[i],&q[i]);
2171:  }
2172:   PetscFree(q);
2173:   return(0);
2174: }

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

2179:    Not Collective

2181:    Input Parameters:
2182: +  x - the vector
2183: -  a - location of pointer to array obtained from VecGetArray()

2185:    Level: beginner

2187:    Notes:
2188:    For regular PETSc vectors this routine does not involve any copies. For
2189:    any special vectors that do not store local vector data in a contiguous
2190:    array, this routine will copy the data back into the underlying 
2191:    vector data structure from the array obtained with VecGetArray().

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

2197:    Fortran Note:
2198:    This routine is used differently from Fortran 77
2199: $    Vec         x
2200: $    PetscScalar x_array(1)
2201: $    PetscOffset i_x
2202: $    int         ierr
2203: $       call VecGetArray(x,x_array,i_x,ierr)
2204: $
2205: $   Access first local entry in vector with
2206: $      value = x_array(i_x + 1)
2207: $
2208: $      ...... other code
2209: $       call VecRestoreArray(x,x_array,i_x,ierr)

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

2215: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2216: M*/
2219: int VecRestoreArray_Private(Vec x,PetscScalar *a[])
2220: {

2227: #if defined(PETSC_USE_BOPT_g)
2228:   CHKMEMQ;
2229: #endif
2230:   if (x->ops->restorearray) {
2231:     (*x->ops->restorearray)(x,a);
2232:   }
2233:   PetscObjectIncreaseState((PetscObject)x);
2234:   return(0);
2235: }

2237: #undef  __FUNCT__
2239: /*@
2240:   VecViewFromOptions - This function visualizes the vector based upon user options.

2242:   Collective on Vec

2244:   Input Parameters:
2245: . vec   - The vector
2246: . title - The title

2248:   Level: intermediate

2250: .keywords: Vec, view, options, database
2251: .seealso: VecSetFromOptions(), VecView()
2252: @*/
2253: int VecViewFromOptions(Vec vec, char *title)
2254: {
2255:   PetscViewer viewer;
2256:   PetscDraw   draw;
2257:   PetscTruth  opt;
2258:   char       *titleStr;
2259:   char        typeName[1024];
2260:   char        fileName[PETSC_MAX_PATH_LEN];
2261:   int         len;
2262:   int         ierr;

2265:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2266:   if (opt == PETSC_TRUE) {
2267:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2268:     PetscStrlen(typeName, &len);
2269:     if (len > 0) {
2270:       PetscViewerCreate(vec->comm, &viewer);
2271:       PetscViewerSetType(viewer, typeName);
2272:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2273:       if (opt == PETSC_TRUE) {
2274:         PetscViewerSetFilename(viewer, fileName);
2275:       } else {
2276:         PetscViewerSetFilename(viewer, vec->name);
2277:       }
2278:       VecView(vec, viewer);
2279:       PetscViewerFlush(viewer);
2280:       PetscViewerDestroy(viewer);
2281:     } else {
2282:       VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2283:     }
2284:   }
2285:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2286:   if (opt == PETSC_TRUE) {
2287:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2288:     PetscViewerDrawGetDraw(viewer, 0, &draw);
2289:     if (title != PETSC_NULL) {
2290:       titleStr = title;
2291:     } else {
2292:       PetscObjectName((PetscObject) vec);                                                          CHKERRQ(ierr) ;
2293:       titleStr = vec->name;
2294:     }
2295:     PetscDrawSetTitle(draw, titleStr);
2296:     VecView(vec, viewer);
2297:     PetscViewerFlush(viewer);
2298:     PetscDrawPause(draw);
2299:     PetscViewerDestroy(viewer);
2300:   }
2301:   return(0);
2302: }

2306: /*@C
2307:    VecView - Views a vector object. 

2309:    Collective on Vec

2311:    Input Parameters:
2312: +  v - the vector
2313: -  viewer - an optional visualization context

2315:    Notes:
2316:    The available visualization contexts include
2317: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
2318: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2319:          output where only the first processor opens
2320:          the file.  All other processors send their 
2321:          data to the first processor to print. 

2323:    You can change the format the vector is printed using the 
2324:    option PetscViewerSetFormat().

2326:    The user can open alternative visualization contexts with
2327: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
2328: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
2329:          specified file; corresponding input uses VecLoad()
2330: .    PetscViewerDrawOpen() - Outputs vector to an X window display
2331: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

2333:    The user can call PetscViewerSetFormat() to specify the output
2334:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2335:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
2336: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2337: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2338: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2339: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
2340:          format common among all vector types

2342:    Level: beginner

2344:    Concepts: vector^printing
2345:    Concepts: vector^saving to disk

2347: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2348:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2349:           PetscRealView(), PetscScalarView(), PetscIntView()
2350: @*/
2351: int VecView(Vec vec,PetscViewer viewer)
2352: {
2353:   int               ierr;
2354:   PetscViewerFormat format;

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

2364:   /*
2365:      Check if default viewer has been overridden, but user request it anyways
2366:   */
2367:   PetscViewerGetFormat(viewer,&format);
2368:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2369:     PetscViewerPopFormat(viewer);
2370:     (*vec->ops->viewnative)(vec,viewer);
2371:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2372:   } else {
2373:     (*vec->ops->view)(vec,viewer);
2374:   }
2375:   return(0);
2376: }

2380: /*@
2381:    VecGetSize - Returns the global number of elements of the vector.

2383:    Not Collective

2385:    Input Parameter:
2386: .  x - the vector

2388:    Output Parameters:
2389: .  size - the global length of the vector

2391:    Level: beginner

2393:    Concepts: vector^local size

2395: .seealso: VecGetLocalSize()
2396: @*/
2397: int VecGetSize(Vec x,int *size)
2398: {

2405:   (*x->ops->getsize)(x,size);
2406:   return(0);
2407: }

2411: /*@
2412:    VecGetLocalSize - Returns the number of elements of the vector stored 
2413:    in local memory. This routine may be implementation dependent, so use 
2414:    with care.

2416:    Not Collective

2418:    Input Parameter:
2419: .  x - the vector

2421:    Output Parameter:
2422: .  size - the length of the local piece of the vector

2424:    Level: beginner

2426:    Concepts: vector^size

2428: .seealso: VecGetSize()
2429: @*/
2430: int VecGetLocalSize(Vec x,int *size)
2431: {

2438:   (*x->ops->getlocalsize)(x,size);
2439:   return(0);
2440: }

2444: /*@C
2445:    VecGetOwnershipRange - Returns the range of indices owned by 
2446:    this processor, assuming that the vectors are laid out with the
2447:    first n1 elements on the first processor, next n2 elements on the
2448:    second, etc.  For certain parallel layouts this range may not be 
2449:    well defined. 

2451:    Not Collective

2453:    Input Parameter:
2454: .  x - the vector

2456:    Output Parameters:
2457: +  low - the first local element, pass in PETSC_NULL if not interested
2458: -  high - one more than the last local element, pass in PETSC_NULL if not interested

2460:    Note:
2461:    The high argument is one more than the last element stored locally.

2463:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

2465:    Level: beginner

2467:    Concepts: ownership^of vectors
2468:    Concepts: vector^ownership of elements

2470: @*/
2471: int VecGetOwnershipRange(Vec x,int *low,int *high)
2472: {
2473:   int      ierr;

2480:   PetscMapGetLocalRange(x->map,low,high);
2481:   return(0);
2482: }

2486: /*@C
2487:    VecGetPetscMap - Returns the map associated with the vector

2489:    Not Collective

2491:    Input Parameter:
2492: .  x - the vector

2494:    Output Parameters:
2495: .  map - the map

2497:    Level: developer

2499: @*/
2500: int VecGetPetscMap(Vec x,PetscMap *map)
2501: {
2506:   *map = x->map;
2507:   return(0);
2508: }

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

2515:    Collective on Vec

2517:    Input Parameter:
2518: +  x - the vector
2519: -  op - the option

2521:    Supported Options:
2522: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
2523:       entries destined to be stored on a seperate processor. This can be used
2524:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
2525:       that you have only used VecSetValues() to set local elements
2526: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

2528:    Level: intermediate

2530: @*/
2531: int VecSetOption(Vec x,VecOption op)
2532: {

2538:   if (x->ops->setoption) {
2539:     (*x->ops->setoption)(x,op);
2540:   }
2541:   return(0);
2542: }

2546: /* Default routines for obtaining and releasing; */
2547: /* may be used by any implementation */
2548: int VecDuplicateVecs_Default(Vec w,int m,Vec *V[])
2549: {
2550:   int  i,ierr;

2555:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2556:   PetscMalloc(m*sizeof(Vec*),V);
2557:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2558:   return(0);
2559: }

2563: int VecDestroyVecs_Default(const Vec v[], int m)
2564: {
2565:   int i,ierr;

2569:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2570:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
2571:   PetscFree((Vec*)v);
2572:   return(0);
2573: }

2577: /*@
2578:    VecPlaceArray - Allows one to replace the array in a vector with an
2579:    array provided by the user. This is useful to avoid copying an array
2580:    into a vector.

2582:    Not Collective

2584:    Input Parameters:
2585: +  vec - the vector
2586: -  array - the array

2588:    Notes:
2589:    You can return to the original array with a call to VecResetArray()

2591:    Level: developer

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

2595: @*/
2596: int VecPlaceArray(Vec vec,const PetscScalar array[])
2597: {

2604:   if (vec->ops->placearray) {
2605:     (*vec->ops->placearray)(vec,array);
2606:   } else {
2607:     SETERRQ(1,"Cannot place array in this type of vector");
2608:   }
2609:   PetscObjectIncreaseState((PetscObject)vec);
2610:   return(0);
2611: }

2615: /*@
2616:    VecResetArray - Resets a vector to use its default memory. Call this 
2617:    after the use of VecPlaceArray().

2619:    Not Collective

2621:    Input Parameters:
2622: .  vec - the vector

2624:    Level: developer

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

2628: @*/
2629: int VecResetArray(Vec vec)
2630: {

2636:   if (vec->ops->resetarray) {
2637:     (*vec->ops->resetarray)(vec);
2638:   } else {
2639:     SETERRQ(1,"Cannot reset array in this type of vector");
2640:   }
2641:   PetscObjectIncreaseState((PetscObject)vec);
2642:   return(0);
2643: }

2647: /*@C
2648:    VecReplaceArray - Allows one to replace the array in a vector with an
2649:    array provided by the user. This is useful to avoid copying an array
2650:    into a vector.

2652:    Not Collective

2654:    Input Parameters:
2655: +  vec - the vector
2656: -  array - the array

2658:    Notes:
2659:    This permanently replaces the array and frees the memory associated
2660:    with the old array.

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

2665:    Not supported from Fortran

2667:    Level: developer

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

2671: @*/
2672: int VecReplaceArray(Vec vec,const PetscScalar array[])
2673: {

2679:   if (vec->ops->replacearray) {
2680:     (*vec->ops->replacearray)(vec,array);
2681:  } else {
2682:     SETERRQ(1,"Cannot replace array in this type of vector");
2683:   }
2684:   PetscObjectIncreaseState((PetscObject)vec);
2685:   return(0);
2686: }

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

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

2695:     Collective on Vec

2697:     Input Parameters:
2698: +   x - a vector to mimic
2699: -   n - the number of vectors to obtain

2701:     Output Parameters:
2702: +   y - Fortran90 pointer to the array of vectors
2703: -   ierr - error code

2705:     Example of Usage: 
2706: .vb
2707:     Vec x
2708:     Vec, pointer :: y(:)
2709:     ....
2710:     call VecDuplicateVecsF90(x,2,y,ierr)
2711:     call VecSet(alpha,y(2),ierr)
2712:     call VecSet(alpha,y(2),ierr)
2713:     ....
2714:     call VecDestroyVecsF90(y,2,ierr)
2715: .ve

2717:     Notes:
2718:     Not yet supported for all F90 compilers

2720:     Use VecDestroyVecsF90() to free the space.

2722:     Level: beginner

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

2726: M*/

2728: /*MC
2729:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2730:     VecGetArrayF90().

2732:     Synopsis:
2733:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2735:     Not collective

2737:     Input Parameters:
2738: +   x - vector
2739: -   xx_v - the Fortran90 pointer to the array

2741:     Output Parameter:
2742: .   ierr - error code

2744:     Example of Usage: 
2745: .vb
2746:     PetscScalar, pointer :: xx_v(:)
2747:     ....
2748:     call VecGetArrayF90(x,xx_v,ierr)
2749:     a = xx_v(3)
2750:     call VecRestoreArrayF90(x,xx_v,ierr)
2751: .ve
2752:    
2753:     Notes:
2754:     Not yet supported for all F90 compilers

2756:     Level: beginner

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

2760: M*/

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

2765:     Synopsis:
2766:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

2768:     Input Parameters:
2769: +   x - pointer to array of vector pointers
2770: -   n - the number of vectors previously obtained

2772:     Output Parameter:
2773: .   ierr - error code

2775:     Notes:
2776:     Not yet supported for all F90 compilers

2778:     Level: beginner

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

2782: M*/

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

2790:     Synopsis:
2791:     VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2793:     Not Collective 

2795:     Input Parameter:
2796: .   x - vector

2798:     Output Parameters:
2799: +   xx_v - the Fortran90 pointer to the array
2800: -   ierr - error code

2802:     Example of Usage: 
2803: .vb
2804:     PetscScalar, pointer :: xx_v(:)
2805:     ....
2806:     call VecGetArrayF90(x,xx_v,ierr)
2807:     a = xx_v(3)
2808:     call VecRestoreArrayF90(x,xx_v,ierr)
2809: .ve

2811:     Notes:
2812:     Not yet supported for all F90 compilers

2814:     Level: beginner

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

2818: M*/

2822: /*@C 
2823:   VecLoadIntoVector - Loads a vector that has been stored in binary format
2824:   with VecView().

2826:   Collective on PetscViewer 

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

2832:   Level: intermediate

2834:   Notes:
2835:   The input file must contain the full global vector, as
2836:   written by the routine VecView().

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

2840:   Notes for advanced users:
2841:   Most users should not need to know the details of the binary storage
2842:   format, since VecLoad() and VecView() completely hide these details.
2843:   But for anyone who's interested, the standard binary matrix storage
2844:   format is
2845: .vb
2846:      int    VEC_FILE_COOKIE
2847:      int    number of rows
2848:      PetscScalar *values of all nonzeros
2849: .ve

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

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

2864:    Concepts: vector^loading from file

2866: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
2867: @*/
2868: int VecLoadIntoVector(PetscViewer viewer,Vec vec)
2869: {

2876:   if (!vec->ops->loadintovector) {
2877:     SETERRQ(1,"Vector does not support load");
2878:   }
2879:   (*vec->ops->loadintovector)(viewer,vec);
2880:   PetscObjectIncreaseState((PetscObject)vec);
2881:   return(0);
2882: }

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

2889:    Collective on Vec

2891:    Input Parameter:
2892: .  v - the vector 

2894:    Output Parameter:
2895: .  v - the vector reciprocal

2897:    Level: intermediate

2899:    Concepts: vector^reciprocal

2901: @*/
2902: int VecReciprocal(Vec vec)
2903: {
2904:   int    ierr;

2909:   if (!vec->ops->reciprocal) {
2910:     SETERRQ(1,"Vector does not support reciprocal operation");
2911:   }
2912:   (*vec->ops->reciprocal)(vec);
2913:   PetscObjectIncreaseState((PetscObject)vec);
2914:   return(0);
2915: }

2919: int VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2920: {
2923:   /* save the native version of the viewer */
2924:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
2925:     vec->ops->viewnative = vec->ops->view;
2926:   }
2927:   (((void(**)(void))vec->ops)[(int)op]) = f;
2928:   return(0);
2929: }

2933: /*@
2934:    VecSetStashInitialSize - sets the sizes of the vec-stash, that is
2935:    used during the assembly process to store values that belong to 
2936:    other processors.

2938:    Collective on Vec

2940:    Input Parameters:
2941: +  vec   - the vector
2942: .  size  - the initial size of the stash.
2943: -  bsize - the initial size of the block-stash(if used).

2945:    Options Database Keys:
2946: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2947: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

2949:    Level: intermediate

2951:    Notes: 
2952:      The block-stash is used for values set with VecSetValuesBlocked() while
2953:      the stash is used for values set with VecSetValues()

2955:      Run with the option -log_info and look for output of the form
2956:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2957:      to determine the appropriate value, MM, to use for size and 
2958:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2959:      to determine the value, BMM to use for bsize

2961:    Concepts: vector^stash
2962:    Concepts: stash^vector

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

2966: @*/
2967: int VecSetStashInitialSize(Vec vec,int size,int bsize)
2968: {

2973:   VecStashSetInitialSize_Private(&vec->stash,size);
2974:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
2975:   return(0);
2976: }

2980: /*@
2981:    VecStashView - Prints the entries in the vector stash and block stash.

2983:    Collective on Vec

2985:    Input Parameters:
2986: +  vec   - the vector
2987: -  viewer - the viewer

2989:    Level: advanced

2991:    Concepts: vector^stash
2992:    Concepts: stash^vector

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

2996: @*/
2997: int VecStashView(Vec v,PetscViewer viewer)
2998: {
2999:   int          ierr,rank,i,j;
3000:   PetscTruth   match;
3001:   VecStash     *s;
3002:   PetscScalar  val;


3009:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3010:   if (!match) SETERRQ1(1,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3011:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3012:   MPI_Comm_rank(v->comm,&rank);
3013:   s = &v->bstash;

3015:   /* print block stash */
3016:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %d block size %d\n",rank,s->n,s->bs);
3017:   for (i=0; i<s->n; i++) {
3018:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d ",rank,s->idx[i]);
3019:     for (j=0; j<s->bs; j++) {
3020:       val = s->array[i*s->bs+j];
3021: #if defined(PETSC_USE_COMPLEX)
3022:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3023: #else
3024:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3025: #endif
3026:     }
3027:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3028:   }
3029:   PetscViewerFlush(viewer);

3031:   s = &v->stash;

3033:   /* print basic stash */
3034:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %d\n",rank,s->n);
3035:   for (i=0; i<s->n; i++) {
3036:     val = s->array[i];
3037: #if defined(PETSC_USE_COMPLEX)
3038:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3039: #else
3040:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d %18.16e\n",rank,s->idx[i],val);
3041: #endif
3042:   }
3043:   PetscViewerFlush(viewer);

3045:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3046:   return(0);
3047: }

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

3056:    Not Collective

3058:    Input Parameter:
3059: +  x - the vector
3060: .  m - first dimension of two dimensional array
3061: .  n - second dimension of two dimensional array
3062: .  mstart - first index you will use in first coordinate direction (often 0)
3063: -  nstart - first index in the second coordinate direction (often 0)

3065:    Output Parameter:
3066: .  a - location to put pointer to the array

3068:    Level: beginner

3070:   Notes:
3071:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3072:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3073:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3074:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3075:    
3076:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3080: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3081:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3082:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3083: @*/
3084: int VecGetArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
3085: {
3086:   int         i,ierr,N;
3087:   PetscScalar *aa;

3093:   VecGetLocalSize(x,&N);
3094:   if (m*n != N) SETERRQ3(1,"Local array size %d does not match 2d array dimensions %d by %d",N,m,n);
3095:   VecGetArray(x,&aa);

3097:   PetscMalloc(m*sizeof(PetscScalar*),a);
3098:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3099:   *a -= mstart;
3100:   return(0);
3101: }

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

3108:    Not Collective

3110:    Input Parameters:
3111: +  x - the vector
3112: .  m - first dimension of two dimensional array
3113: .  n - second dimension of the two dimensional array
3114: .  mstart - first index you will use in first coordinate direction (often 0)
3115: .  nstart - first index in the second coordinate direction (often 0)
3116: -  a - location of pointer to array obtained from VecGetArray2d()

3118:    Level: beginner

3120:    Notes:
3121:    For regular PETSc vectors this routine does not involve any copies. For
3122:    any special vectors that do not store local vector data in a contiguous
3123:    array, this routine will copy the data back into the underlying 
3124:    vector data structure from the array obtained with VecGetArray().

3126:    This routine actually zeros out the a pointer. 

3128: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3129:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3130:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3131: @*/
3132: int VecRestoreArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
3133: {

3140:   PetscFree(*a + mstart);
3141:   VecRestoreArray(x,PETSC_NULL);
3142:   return(0);
3143: }

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

3152:    Not Collective

3154:    Input Parameter:
3155: +  x - the vector
3156: .  m - first dimension of two dimensional array
3157: -  mstart - first index you will use in first coordinate direction (often 0)

3159:    Output Parameter:
3160: .  a - location to put pointer to the array

3162:    Level: beginner

3164:   Notes:
3165:    For a vector obtained from DACreateLocalVector() mstart are likely
3166:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3167:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
3168:    
3169:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3171: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3172:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3173:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3174: @*/
3175: int VecGetArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3176: {
3177:   int ierr,N;

3183:   VecGetLocalSize(x,&N);
3184:   if (m != N) SETERRQ2(1,"Local array size %d does not match 1d array dimensions %d",N,m);
3185:   VecGetArray(x,a);
3186:   *a  -= mstart;
3187:   return(0);
3188: }

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

3195:    Not Collective

3197:    Input Parameters:
3198: +  x - the vector
3199: .  m - first dimension of two dimensional array
3200: .  mstart - first index you will use in first coordinate direction (often 0)
3201: -  a - location of pointer to array obtained from VecGetArray21()

3203:    Level: beginner

3205:    Notes:
3206:    For regular PETSc vectors this routine does not involve any copies. For
3207:    any special vectors that do not store local vector data in a contiguous
3208:    array, this routine will copy the data back into the underlying 
3209:    vector data structure from the array obtained with VecGetArray1d().

3211:    This routine actually zeros out the a pointer. 

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

3215: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3216:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3217:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3218: @*/
3219: int VecRestoreArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3220: {

3226:   VecRestoreArray(x,PETSC_NULL);
3227:   return(0);
3228: }

3232: /*@C
3233:    VecConjugate - Conjugates a vector.

3235:    Collective on Vec

3237:    Input Parameters:
3238: .  x - the vector

3240:    Level: intermediate

3242:    Concepts: vector^conjugate

3244: @*/
3245: int VecConjugate(Vec x)
3246: {
3247: #ifdef PETSC_USE_COMPLEX

3253:   (*x->ops->conjugate)(x);
3254:   /* we need to copy norms here */
3255:   PetscObjectIncreaseState((PetscObject)x);
3256:   return(0);
3257: #else
3258:   return(0);
3259: #endif
3260: }

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

3269:    Not Collective

3271:    Input Parameter:
3272: +  x - the vector
3273: .  m - first dimension of three dimensional array
3274: .  n - second dimension of three dimensional array
3275: .  p - third dimension of three dimensional array
3276: .  mstart - first index you will use in first coordinate direction (often 0)
3277: .  nstart - first index in the second coordinate direction (often 0)
3278: -  pstart - first index in the third coordinate direction (often 0)

3280:    Output Parameter:
3281: .  a - location to put pointer to the array

3283:    Level: beginner

3285:   Notes:
3286:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3287:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3288:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3289:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3290:    
3291:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3295: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3296:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3297:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3298: @*/
3299: int VecGetArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3300: {
3301:   int         i,ierr,N,j;
3302:   PetscScalar *aa,**b;

3308:   VecGetLocalSize(x,&N);
3309:   if (m*n*p != N) SETERRQ4(1,"Local array size %d does not match 3d array dimensions %d by %d by %d",N,m,n,p);
3310:   VecGetArray(x,&aa);

3312:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3313:   b    = (PetscScalar **)((*a) + m);
3314:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
3315:   for (i=0; i<m; i++) {
3316:     for (j=0; j<n; j++) {
3317:       b[i*n+j] = aa + i*n*p + j*p - pstart;
3318:     }
3319:   }
3320:   *a -= mstart;
3321:   return(0);
3322: }

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

3329:    Not Collective

3331:    Input Parameters:
3332: +  x - the vector
3333: .  m - first dimension of three dimensional array
3334: .  n - second dimension of the three dimensional array
3335: .  p - third dimension of the three dimensional array
3336: .  mstart - first index you will use in first coordinate direction (often 0)
3337: .  nstart - first index in the second coordinate direction (often 0)
3338: .  pstart - first index in the third coordinate direction (often 0)
3339: -  a - location of pointer to array obtained from VecGetArray3d()

3341:    Level: beginner

3343:    Notes:
3344:    For regular PETSc vectors this routine does not involve any copies. For
3345:    any special vectors that do not store local vector data in a contiguous
3346:    array, this routine will copy the data back into the underlying 
3347:    vector data structure from the array obtained with VecGetArray().

3349:    This routine actually zeros out the a pointer. 

3351: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3352:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3353:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3354: @*/
3355: int VecRestoreArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3356: {

3363:   PetscFree(*a + mstart);
3364:   VecRestoreArray(x,PETSC_NULL);
3365:   return(0);
3366: }