Actual source code: vector.c

  1: #define PETSCVEC_DLL

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

  9: /* Logging support */
 10: PetscCookie PETSCVEC_DLLEXPORT VEC_COOKIE = 0;
 11: 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;
 12: 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;
 13: PetscEvent  VEC_MTDot = 0, VEC_NormBarrier = 0, VEC_MAXPY = 0, VEC_Swap = 0, VEC_AssemblyBegin = 0, VEC_ScatterBegin = 0, VEC_ScatterEnd = 0;
 14: PetscEvent  VEC_AssemblyEnd = 0, VEC_PointwiseMult = 0, VEC_SetValues = 0, VEC_Load = 0, VEC_ScatterBarrier = 0;
 15: PetscEvent  VEC_SetRandom = 0, VEC_ReduceArithmetic = 0, VEC_ReduceBarrier = 0, VEC_ReduceCommunication = 0;

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

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

 27:   Collective on Vec

 29:   Input Parameter:
 30: . vec - The vector

 32:   Level: intermediate

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

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

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

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

 74:   Collective on Vec

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

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

 82:   Level: beginner

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

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


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

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

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

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

115:   VecViewFromOptions(vec, vec->name);
116:   return(0);
117: }

121: /*@
122:   VecPrintHelp - Prints some options for the Vec.

124:   Input Parameter:
125: . vec - The vector

127:   Options Database Keys:
128: $  -help, -h

130:   Level: intermediate

132: .keywords: Vec, help
133: .seealso: VecSetFromOptions()
134: @*/
135: PetscErrorCode PETSCVEC_DLLEXPORT VecPrintHelp(Vec vec)
136: {
139:   return(0);
140: }

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

147:   Collective on Vec

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

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

158:   Level: intermediate

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

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

179:    Collective on Vec

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

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

188:    Level: advanced

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

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

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

216:    Collective on Vec

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

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

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

227:    Level: advanced

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

231:    Concepts: vector^block size
232:    Concepts: block^vector

234: @*/
235: PetscErrorCode PETSCVEC_DLLEXPORT VecGetBlockSize(Vec v,PetscInt *bs)
236: {
240:   *bs = v->bs;
241:   return(0);
242: }

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

249:    Not Collective

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

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

258:    Level: developer

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

273: /*@C
274:    VecSetOptionsPrefix - Sets the prefix used for searching for all 
275:    Vec options in the database.

277:    Collective on Vec

279:    Input Parameter:
280: +  v - the Vec context
281: -  prefix - the prefix to prepend to all option names

283:    Notes:
284:    A hyphen (-) must NOT be given at the beginning of the prefix name.
285:    The first character of all runtime options is AUTOVECICALLY the hyphen.

287:    Level: advanced

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

291: .seealso: VecSetFromOptions()
292: @*/
293: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOptionsPrefix(Vec v,const char prefix[])
294: {

299:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
300:   return(0);
301: }

305: /*@C
306:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all 
307:    Vec options in the database.

309:    Collective on Vec

311:    Input Parameters:
312: +  v - the Vec context
313: -  prefix - the prefix to prepend to all option names

315:    Notes:
316:    A hyphen (-) must NOT be given at the beginning of the prefix name.
317:    The first character of all runtime options is AUTOVECICALLY the hyphen.

319:    Level: advanced

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

323: .seealso: VecGetOptionsPrefix()
324: @*/
325: PetscErrorCode PETSCVEC_DLLEXPORT VecAppendOptionsPrefix(Vec v,const char prefix[])
326: {
328: 
331:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
332:   return(0);
333: }

337: /*@C
338:    VecGetOptionsPrefix - Sets the prefix used for searching for all 
339:    Vec options in the database.

341:    Not Collective

343:    Input Parameter:
344: .  A - the Vec context

346:    Output Parameter:
347: .  prefix - pointer to the prefix string used

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

352:    Level: advanced

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

356: .seealso: VecAppendOptionsPrefix()
357: @*/
358: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOptionsPrefix(Vec v,const char *prefix[])
359: {

364:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
365:   return(0);
366: }

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

373:    Collective on Vec

375:    Input Parameters:
376: .  v - the Vec context

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

382:    Level: advanced

384: .keywords: Vec, setup

386: .seealso: VecCreate(), VecDestroy()
387: @*/
388: PetscErrorCode PETSCVEC_DLLEXPORT VecSetUp(Vec v)
389: {

394:   VecSetFromOptions(v);
395:   return(0);
396: }

400: /*@
401:    VecDot - Computes the vector dot product.

403:    Collective on Vec

405:    Input Parameters:
406: .  x, y - the vectors

408:    Output Parameter:
409: .  alpha - the dot product

411:    Performance Issues:
412: +    per-processor memory bandwidth
413: .    interprocessor latency
414: -    work load inbalance that causes certain processes to arrive much earlier than
415:      others

417:    Notes for Users of Complex Numbers:
418:    For complex vectors, VecDot() computes 
419: $     val = (x,y) = y^H x,
420:    where y^H denotes the conjugate transpose of y.

422:    Use VecTDot() for the indefinite form
423: $     val = (x,y) = y^T x,
424:    where y^T denotes the transpose of y.

426:    Level: intermediate

428:    Concepts: inner product
429:    Concepts: vector^inner product

431: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
432: @*/
433: PetscErrorCode PETSCVEC_DLLEXPORT VecDot(Vec x,Vec y,PetscScalar *val)
434: {

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

447:   PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,x->comm);
448:   (*x->ops->dot)(x,y,val);
449:   PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,x->comm);
450:   return(0);
451: }

455: /*@
456:    VecNorm  - Computes the vector norm.

458:    Collective on Vec

460:    Input Parameters:
461: +  x - the vector
462: -  type - one of NORM_1, NORM_2, NORM_INFINITY.  Also available
463:           NORM_1_AND_2, which computes both norms and stores them
464:           in a two element array.

466:    Output Parameter:
467: .  val - the norm 

469:    Notes:
470: $     NORM_1 denotes sum_i |x_i|
471: $     NORM_2 denotes sqrt(sum_i (x_i)^2)
472: $     NORM_INFINITY denotes max_i |x_i|

474:    Level: intermediate

476:    Performance Issues:
477: +    per-processor memory bandwidth
478: .    interprocessor latency
479: -    work load inbalance that causes certain processes to arrive much earlier than
480:      others

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

487:    Concepts: norm
488:    Concepts: vector^norm

490: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), 
491:           VecNormBegin(), VecNormEnd()

493: @*/
494: PetscErrorCode PETSCVEC_DLLEXPORT VecNorm(Vec x,NormType type,PetscReal *val)
495: {
496:   PetscTruth     flg;
498:   PetscInt       type_id;


505:   /*
506:    * Cached data?
507:    */
508:   if (type!=NORM_1_AND_2) {
509:     VecNormComposedDataID(type,&type_id);
510:     PetscObjectComposedDataGetReal((PetscObject)x,type_id,*val,flg);
511:     if (flg) return(0);
512:   }
513: 

515:   PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
516:   (*x->ops->norm)(x,type,val);
517:   PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);

519:   if (type!=NORM_1_AND_2) {
520:     PetscObjectComposedDataSetReal((PetscObject)x,type_id,*val);
521:   }

523:   return(0);
524: }

528: PetscErrorCode PETSCVEC_DLLEXPORT VecNormComposedDataID(NormType type,PetscInt *type_id)
529: {
530:   static PetscInt id_norm1=-1,id_norm2=-1,id_normInf=-1,id_normF=-1,id_norm12=-1;
531:   PetscErrorCode  ierr;

534:   switch (type) {
535:   case NORM_1 :
536:     if (id_norm1==-1) {
537:       PetscObjectComposedDataRegister(&id_norm1);}
538:     *type_id = id_norm1; break;
539:   case NORM_2 :
540:     if (id_norm2==-1) {
541:       PetscObjectComposedDataRegister(&id_norm2);}
542:     *type_id = id_norm2; break;
543:   case NORM_1_AND_2 :
544:     /* we don't handle this one yet */
545:     if (id_norm1==-1) {
546:       PetscObjectComposedDataRegister(&id_norm1);}
547:     if (id_norm2==-1) {
548:       PetscObjectComposedDataRegister(&id_norm2);}
549:     *type_id = id_norm12; break;
550:   case NORM_INFINITY :
551:     if (id_normInf==-1) {
552:       PetscObjectComposedDataRegister(&id_normInf);}
553:     *type_id = id_normInf; break;
554:   case NORM_FROBENIUS :
555:     if (id_normF==-1) {
556:       PetscObjectComposedDataRegister(&id_normF);}
557:     *type_id = id_normF; break;
558:   }
559:   return(0);
560: }

564: /*@
565:    VecNormalize - Normalizes a vector by 2-norm. 

567:    Collective on Vec

569:    Input Parameters:
570: +  x - the vector

572:    Output Parameter:
573: .  x - the normalized vector
574: -  val - the vector norm before normalization

576:    Level: intermediate

578:    Concepts: vector^normalizing
579:    Concepts: normalizing^vector

581: @*/
582: PetscErrorCode PETSCVEC_DLLEXPORT VecNormalize(Vec x,PetscReal *val)
583: {

590:   PetscLogEventBegin(VEC_Normalize,x,0,0,0);
591:   VecNorm(x,NORM_2,val);
592:   if (!*val) {
593:     PetscLogInfo((x,"VecNormalize:Vector of zero norm can not be normalized; Returning only the zero norm\n"));
594:   } else {
595:     PetscScalar tmp = 1.0/(*val);
596:     VecScale(x,tmp);
597:   }

599:   PetscLogEventEnd(VEC_Normalize,x,0,0,0);
600:   return(0);
601: }

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

608:    Collective on Vec

610:    Input Parameter:
611: .  x - the vector

613:    Output Parameters:
614: +  val - the maximum component
615: -  p - the location of val

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

620:    Level: intermediate

622:    Concepts: maximum^of vector
623:    Concepts: vector^maximum value

625: .seealso: VecNorm(), VecMin()
626: @*/
627: PetscErrorCode PETSCVEC_DLLEXPORT VecMax(Vec x,PetscInt *p,PetscReal *val)
628: {

635:   PetscLogEventBegin(VEC_Max,x,0,0,0);
636:   (*x->ops->max)(x,p,val);
637:   PetscLogEventEnd(VEC_Max,x,0,0,0);
638:   return(0);
639: }

643: /*@
644:    VecMin - Determines the minimum vector component and its location.

646:    Collective on Vec

648:    Input Parameters:
649: .  x - the vector

651:    Output Parameter:
652: +  val - the minimum component
653: -  p - the location of val

655:    Level: intermediate

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

660:    Concepts: minimum^of vector
661:    Concepts: vector^minimum entry

663: .seealso: VecMax()
664: @*/
665: PetscErrorCode PETSCVEC_DLLEXPORT VecMin(Vec x,PetscInt *p,PetscReal *val)
666: {

673:   PetscLogEventBegin(VEC_Min,x,0,0,0);
674:   (*x->ops->min)(x,p,val);
675:   PetscLogEventEnd(VEC_Min,x,0,0,0);
676:   return(0);
677: }

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

685:    Collective on Vec

687:    Input Parameters:
688: .  x, y - the vectors

690:    Output Parameter:
691: .  val - the dot product

693:    Notes for Users of Complex Numbers:
694:    For complex vectors, VecTDot() computes the indefinite form
695: $     val = (x,y) = y^T x,
696:    where y^T denotes the transpose of y.

698:    Use VecDot() for the inner product
699: $     val = (x,y) = y^H x,
700:    where y^H denotes the conjugate transpose of y.

702:    Level: intermediate

704:    Concepts: inner product^non-Hermitian
705:    Concepts: vector^inner product
706:    Concepts: non-Hermitian inner product

708: .seealso: VecDot(), VecMTDot()
709: @*/
710: PetscErrorCode PETSCVEC_DLLEXPORT VecTDot(Vec x,Vec y,PetscScalar *val)
711: {

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

724:   PetscLogEventBegin(VEC_TDot,x,y,0,0);
725:   (*x->ops->tdot)(x,y,val);
726:   PetscLogEventEnd(VEC_TDot,x,y,0,0);
727:   return(0);
728: }

732: /*@
733:    VecScale - Scales a vector. 

735:    Collective on Vec

737:    Input Parameters:
738: +  x - the vector
739: -  alpha - the scalar

741:    Output Parameter:
742: .  x - the scaled vector

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

748:    Level: intermediate

750:    Concepts: vector^scaling
751:    Concepts: scaling^vector

753: @*/
754: PetscErrorCode PETSCVEC_DLLEXPORT VecScale (Vec x, PetscScalar alpha)
755: {
756:   PetscReal      scale,norm1=0.0,norm2=0.0,normInf=0.0,normF=0.0;
757:   PetscTruth     flg1,flg2,flgInf,flgF;
759:   PetscInt       type_id1,type_id2,type_idInf,type_idF;

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

768:   /*
769:    * Update cached data
770:    */
771:   /* see if we have cached norms */
772:   /* 1 */
773:   VecNormComposedDataID(NORM_1,&type_id1);
774:   PetscObjectComposedDataGetReal((PetscObject)x,type_id1,norm1,flg1);
775:   /* 2 */
776:   VecNormComposedDataID(NORM_2,&type_id2);
777:   PetscObjectComposedDataGetReal((PetscObject)x,type_id2,norm2,flg2);
778:   /* inf */
779:   VecNormComposedDataID(NORM_INFINITY,&type_idInf);
780:   PetscObjectComposedDataGetReal((PetscObject)x,type_idInf,normInf,flgInf);
781:   /* frobenius */
782:   VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
783:   PetscObjectComposedDataGetReal((PetscObject)x,type_idF,normF,flgF);

785:   /* in general we consider this object touched */
786:   PetscObjectStateIncrease((PetscObject)x);

788:   /* however, norms can be simply updated */
789:   scale = PetscAbsScalar(alpha);
790:   /* 1 */
791:   if (flg1) {
792:     PetscObjectComposedDataSetReal((PetscObject)x,type_id1,scale*norm1);
793:   }
794:   /* 2 */
795:   if (flg2) {
796:     PetscObjectComposedDataSetReal((PetscObject)x,type_id2,scale*norm2);
797:   }
798:   /* inf */
799:   if (flgInf) {
800:     PetscObjectComposedDataSetReal((PetscObject)x,type_idInf,scale*normInf);
801:   }
802:   /* frobenius */
803:   if (flgF) {
804:     PetscObjectComposedDataSetReal((PetscObject)x,type_idF,scale*normF);
805:   }

807:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
808:   return(0);
809: }

813: /*@
814:    VecCopy - Copies a vector. 

816:    Collective on Vec

818:    Input Parameter:
819: .  x - the vector

821:    Output Parameter:
822: .  y - the copy

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

828:    Level: beginner

830: .seealso: VecDuplicate()
831: @*/
832: PetscErrorCode PETSCVEC_DLLEXPORT VecCopy(Vec x,Vec y)
833: {
834:   PetscTruth     flg;
835:   PetscReal      norm=0.0;
837:   PetscInt       type_id;

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

848:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
849:   (*x->ops->copy)(x,y);

851:   /*
852:    * Update cached data
853:    */
854:   /* in general we consider this object touched */
855:   PetscObjectStateIncrease((PetscObject)y);
856:   /* however, norms can be simply copied over */
857:   /* 2 */
858:   VecNormComposedDataID(NORM_2,&type_id);
859:   PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
860:   if (flg) {
861:     PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
862:   }
863:   /* 1 */
864:   VecNormComposedDataID(NORM_1,&type_id);
865:   PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
866:   if (flg) {
867:     PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
868:   }
869:   /* inf */
870:   VecNormComposedDataID(NORM_INFINITY,&type_id);
871:   PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
872:   if (flg) {
873:     PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
874:   }
875:   /* frobenius */
876:   VecNormComposedDataID(NORM_FROBENIUS,&type_id);
877:   PetscObjectComposedDataGetReal((PetscObject)x,type_id,norm,flg);
878:   if (flg) {
879:     PetscObjectComposedDataSetReal((PetscObject)y,type_id,norm);
880:   }

882:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
883:   return(0);
884: }

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

891:    Collective on Vec

893:    Input Parameters:
894: +  x  - the vector
895: -  alpha - the scalar

897:    Output Parameter:
898: .  x  - the vector

900:    Note:
901:    For a vector of dimension n, VecSet() computes
902: $     x[i] = alpha, for i=1,...,n,
903:    so that all vector entries then equal the identical
904:    scalar value, alpha.  Use the more general routine
905:    VecSetValues() to set different vector entries.

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

910:    Level: beginner

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

914:    Concepts: vector^setting to constant

916: @*/
917: PetscErrorCode PETSCVEC_DLLEXPORT VecSet(Vec x,PetscScalar alpha)
918: {
919:   PetscReal      val;
921:   PetscInt       type_id;

926:   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()");
927: #if defined (PETSC_USE_DEBUG)
928:  {
929:    PetscReal alpha_local,alpha_max;
930:    alpha_local = PetscAbsScalar(alpha);
931:    MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,x->comm);
932:    if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
933:  }
934: #endif

936:   PetscLogEventBegin(VEC_Set,x,0,0,0);
937:   (*x->ops->set)(x,alpha);
938:   PetscLogEventEnd(VEC_Set,x,0,0,0);

940:   /*
941:    * Update cached data
942:    */
943:   /* in general we consider this object touched */
944:   PetscObjectStateIncrease((PetscObject)x);
945:   /* however, norms can be simply set */
946:   /* 1 */
947:   val = PetscAbsScalar(alpha);
948:   VecNormComposedDataID(NORM_1,&type_id);
949:   PetscObjectComposedDataSetReal((PetscObject)x,type_id,x->N * val);
950:   /* inf */
951:   VecNormComposedDataID(NORM_INFINITY,&type_id);
952:   PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);
953:   /* 2 */
954:   val = sqrt((double)x->N) * val;
955:   VecNormComposedDataID(NORM_2,&type_id);
956:   PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);
957:   /* frobenius */
958:   VecNormComposedDataID(NORM_FROBENIUS,&type_id);
959:   PetscObjectComposedDataSetReal((PetscObject)x,type_id,val);

961:   return(0);
962: }

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

969:    Collective on Vec

971:    Input Parameters:
972: +  x  - the vector
973: -  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
974:           it will create one internally.

976:    Output Parameter:
977: .  x  - the vector

979:    Example of Usage:
980: .vb
981:      PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
982:      VecSetRandom(x,rctx);
983:      PetscRandomDestroy(rctx);
984: .ve

986:    Level: intermediate

988:    Concepts: vector^setting to random
989:    Concepts: random^vector

991: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
992: @*/
993: PetscErrorCode PETSCVEC_DLLEXPORT VecSetRandom(Vec x,PetscRandom rctx)
994: {
996:   PetscRandom    randObj = PETSC_NULL;

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

1004:   if (!rctx) {
1005:     MPI_Comm    comm;
1006:     PetscObjectGetComm((PetscObject)x,&comm);
1007:     PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
1008:     rctx = randObj;
1009:   }

1011:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
1012:   (*x->ops->setrandom)(x,rctx);
1013:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
1014: 
1015:   if (randObj) {
1016:     PetscRandomDestroy(randObj);
1017:   }
1018:   PetscObjectStateIncrease((PetscObject)x);
1019:   return(0);
1020: }

1024: /*@
1025:    VecAXPY - Computes y = alpha x + y. 

1027:    Collective on Vec

1029:    Input Parameters:
1030: +  alpha - the scalar
1031: -  x, y  - the vectors

1033:    Output Parameter:
1034: .  y - output vector

1036:    Level: intermediate

1038:    Concepts: vector^BLAS
1039:    Concepts: BLAS

1041: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
1042: @*/
1043: PetscErrorCode PETSCVEC_DLLEXPORT VecAXPY(Vec y,PetscScalar alpha,Vec x)
1044: {

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

1056:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
1057:   (*y->ops->axpy)(y,alpha,x);
1058:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
1059:   PetscObjectStateIncrease((PetscObject)y);
1060:   return(0);
1061: }

1065: /*@
1066:    VecAXPBY - Computes y = alpha x + beta y. 

1068:    Collective on Vec

1070:    Input Parameters:
1071: +  alpha,beta - the scalars
1072: -  x, y  - the vectors

1074:    Output Parameter:
1075: .  y - output vector

1077:    Level: intermediate

1079:    Concepts: BLAS
1080:    Concepts: vector^BLAS

1082: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
1083: @*/
1084: PetscErrorCode PETSCVEC_DLLEXPORT VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
1085: {

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

1097:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
1098:   (*y->ops->axpby)(y,alpha,beta,x);
1099:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
1100:   PetscObjectStateIncrease((PetscObject)y);
1101:   return(0);
1102: }

1106: /*@
1107:    VecAYPX - Computes y = x + alpha y.

1109:    Collective on Vec

1111:    Input Parameters:
1112: +  alpha - the scalar
1113: -  x, y  - the vectors

1115:    Output Parameter:
1116: .  y - output vector

1118:    Level: intermediate

1120:    Concepts: vector^BLAS
1121:    Concepts: BLAS

1123: .seealso: VecAXPY(), VecWAXPY()
1124: @*/
1125: PetscErrorCode PETSCVEC_DLLEXPORT VecAYPX(Vec y,PetscScalar alpha,Vec x)
1126: {

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

1138:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
1139:    (*y->ops->aypx)(y,alpha,x);
1140:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
1141:   PetscObjectStateIncrease((PetscObject)y);
1142:   return(0);
1143: }

1147: /*@
1148:    VecSwap - Swaps the vectors x and y.

1150:    Collective on Vec

1152:    Input Parameters:
1153: .  x, y  - the vectors

1155:    Level: advanced

1157:    Concepts: vector^swapping values

1159: @*/
1160: PetscErrorCode PETSCVEC_DLLEXPORT VecSwap(Vec x,Vec y)
1161: {
1162:   PetscReal      norm1x=0.0,norm2x=0.0,normInfx=0.0,normFx=0.0;
1163:   PetscReal      norm1y=0.0,norm2y=0.0,normInfy=0.0,normFy=0.0;
1164:   PetscTruth     flg1x,flg2x,flgInfx,flgFx;
1165:   PetscTruth     flg1y,flg2y,flgInfy,flgFy;
1166:   PetscInt       type_id1,type_id2,type_idInf,type_idF;

1175:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1176:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
1177:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1178:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");

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

1182:   /* See if we have cached norms */
1183:   /* 1 */
1184:   VecNormComposedDataID(NORM_1,&type_id1);
1185:   PetscObjectComposedDataGetReal((PetscObject)x,type_id1,norm1x,flg1x);
1186:   PetscObjectComposedDataGetReal((PetscObject)y,type_id1,norm1y,flg1y);
1187:   /* 2 */
1188:   VecNormComposedDataID(NORM_2,&type_id2);
1189:   PetscObjectComposedDataGetReal((PetscObject)x,type_id2,norm2x,flg2x);
1190:   PetscObjectComposedDataGetReal((PetscObject)y,type_id2,norm2y,flg2y);
1191:   /* inf */
1192:   VecNormComposedDataID(NORM_INFINITY,&type_idInf);
1193:   PetscObjectComposedDataGetReal((PetscObject)x,type_idInf,normInfx,flgInfx);
1194:   PetscObjectComposedDataGetReal((PetscObject)y,type_idInf,normInfy,flgInfy);
1195:   /* frobenius */
1196:   VecNormComposedDataID(NORM_FROBENIUS,&type_idF);
1197:   PetscObjectComposedDataGetReal((PetscObject)x,type_idF,normFx,flgFx);
1198:   PetscObjectComposedDataGetReal((PetscObject)y,type_idF,normFy,flgFy);

1200:   /* Do the actual swap */
1201:   (*x->ops->swap)(x,y);
1202:   PetscObjectStateIncrease((PetscObject)x);
1203:   PetscObjectStateIncrease((PetscObject)y);

1205:   /* Swap any cached norms */
1206:   /* 1 */
1207:   if (flg1x) {
1208:     PetscObjectComposedDataSetReal((PetscObject)y,type_id1,norm1x);
1209:   }
1210:   if (flg1y) {
1211:     PetscObjectComposedDataSetReal((PetscObject)x,type_id1,norm1y);
1212:   }
1213:   /* 2 */
1214:   if (flg2x) {
1215:     PetscObjectComposedDataSetReal((PetscObject)y,type_id2,norm2x);
1216:   }
1217:   if (flg2y) {
1218:     PetscObjectComposedDataSetReal((PetscObject)x,type_id2,norm2y);
1219:   }
1220:   /* inf */
1221:   if (flgInfx) {
1222:     PetscObjectComposedDataSetReal((PetscObject)y,type_idInf,normInfx);
1223:   }
1224:   if (flgInfy) {
1225:     PetscObjectComposedDataSetReal((PetscObject)x,type_idInf,normInfy);
1226:   }
1227:   /* frobenius */
1228:   if (flgFx) {
1229:     PetscObjectComposedDataSetReal((PetscObject)y,type_idF,normFx);
1230:   }
1231:   if (flgFy) {
1232:     PetscObjectComposedDataSetReal((PetscObject)x,type_idF,normFy);
1233:   }

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

1237:   return(0);
1238: }

1242: /*@
1243:    VecWAXPY - Computes w = alpha x + y.

1245:    Collective on Vec

1247:    Input Parameters:
1248: +  alpha - the scalar
1249: -  x, y  - the vectors

1251:    Output Parameter:
1252: .  w - the result

1254:    Level: intermediate

1256:    Concepts: vector^BLAS
1257:    Concepts: BLAS

1259: .seealso: VecAXPY(), VecAYPX()
1260: @*/
1261: PetscErrorCode PETSCVEC_DLLEXPORT VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
1262: {

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

1277:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
1278:    (*w->ops->waxpy)(w,alpha,x,y);
1279:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
1280:   PetscObjectStateIncrease((PetscObject)w);
1281:   return(0);
1282: }

1286: /*@
1287:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

1289:    Collective on Vec

1291:    Input Parameters:
1292: .  x, y  - the vectors

1294:    Output Parameter:
1295: .  w - the result

1297:    Level: advanced

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

1301:    Concepts: vector^pointwise multiply

1303: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1304: @*/
1305: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMult(Vec w, Vec x,Vec y)
1306: {

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

1321:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1322:   (*w->ops->pointwisemult)(w,x,y);
1323:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1324:   PetscObjectStateIncrease((PetscObject)w);
1325:   return(0);
1326: }

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

1333:    Collective on Vec

1335:    Input Parameters:
1336: .  x, y  - the vectors

1338:    Output Parameter:
1339: .  w - the result

1341:    Level: advanced

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

1346:    Concepts: vector^pointwise multiply

1348: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1349: @*/
1350: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMax(Vec w,Vec x,Vec y)
1351: {

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

1366:   (*w->ops->pointwisemax)(w,x,y);
1367:   PetscObjectStateIncrease((PetscObject)w);
1368:   return(0);
1369: }


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

1377:    Collective on Vec

1379:    Input Parameters:
1380: .  x, y  - the vectors

1382:    Output Parameter:
1383: .  w - the result

1385:    Level: advanced

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

1390:    Concepts: vector^pointwise multiply

1392: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1393: @*/
1394: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMin(Vec w,Vec x,Vec y)
1395: {

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

1410:   (*w->ops->pointwisemin)(w,x,y);
1411:   PetscObjectStateIncrease((PetscObject)w);
1412:   return(0);
1413: }

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

1420:    Collective on Vec

1422:    Input Parameters:
1423: .  x, y  - the vectors

1425:    Output Parameter:
1426: .  w - the result

1428:    Level: advanced

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

1432:    Concepts: vector^pointwise multiply

1434: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
1435: @*/
1436: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
1437: {

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

1452:   (*w->ops->pointwisemaxabs)(w,x,y);
1453:   PetscObjectStateIncrease((PetscObject)w);
1454:   return(0);
1455: }

1459: /*@
1460:    VecPointwiseDivide - Computes the componentwise division w = x/y.

1462:    Collective on Vec

1464:    Input Parameters:
1465: .  x, y  - the vectors

1467:    Output Parameter:
1468: .  w - the result

1470:    Level: advanced

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

1474:    Concepts: vector^pointwise divide

1476: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
1477: @*/
1478: PetscErrorCode PETSCVEC_DLLEXPORT VecPointwiseDivide(Vec w,Vec x,Vec y)
1479: {

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

1494:   (*w->ops->pointwisedivide)(w,x,y);
1495:   PetscObjectStateIncrease((PetscObject)w);
1496:   return(0);
1497: }

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

1504:    Collective on Vec

1506:    Input Parameters:
1507: .  x, y  - the vectors

1509:    Output Parameter:
1510: .  max - the result

1512:    Level: advanced

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

1516: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
1517: @*/
1518: PetscErrorCode PETSCVEC_DLLEXPORT VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1519: {

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

1532:   (*x->ops->maxpointwisedivide)(x,y,max);
1533:   return(0);
1534: }

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

1541:    Collective on Vec

1543:    Input Parameters:
1544: .  v - a vector to mimic

1546:    Output Parameter:
1547: .  newv - location to put new vector

1549:    Notes:
1550:    VecDuplicate() does not copy the vector, but rather allocates storage
1551:    for the new vector.  Use VecCopy() to copy a vector.

1553:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1554:    vectors. 

1556:    Level: beginner

1558: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1559: @*/
1560: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicate(Vec x,Vec *newv)
1561: {

1568:   (*x->ops->duplicate)(x,newv);
1569:   PetscObjectStateIncrease((PetscObject)*newv);
1570:   return(0);
1571: }

1575: /*@C
1576:    VecDestroy - Destroys a vector.

1578:    Collective on Vec

1580:    Input Parameters:
1581: .  v  - the vector

1583:    Level: beginner

1585: .seealso: VecDuplicate(), VecDestroyVecs()
1586: @*/
1587: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroy(Vec v)
1588: {

1593:   if (--v->refct > 0) return(0);
1594:   /* destroy the internal part */
1595:   if (v->ops->destroy) {
1596:     (*v->ops->destroy)(v);
1597:   }
1598:   /* destroy the external/common part */
1599:   if (v->mapping) {
1600:     ISLocalToGlobalMappingDestroy(v->mapping);
1601:   }
1602:   if (v->bmapping) {
1603:     ISLocalToGlobalMappingDestroy(v->bmapping);
1604:   }
1605:   if (v->map) {
1606:     PetscMapDestroy(v->map);
1607:   }
1608:   PetscHeaderDestroy(v);
1609:   return(0);
1610: }

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

1617:    Collective on Vec

1619:    Input Parameters:
1620: +  m - the number of vectors to obtain
1621: -  v - a vector to mimic

1623:    Output Parameter:
1624: .  V - location to put pointer to array of vectors

1626:    Notes:
1627:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1628:    vector.

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

1635:    Level: intermediate

1637: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1638: @*/
1639: PetscErrorCode PETSCVEC_DLLEXPORT VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
1640: {

1647:   (*v->ops->duplicatevecs)(v, m,V);
1648:   return(0);
1649: }

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

1656:    Collective on Vec

1658:    Input Parameters:
1659: +  vv - pointer to array of vector pointers
1660: -  m - the number of vectors previously obtained

1662:    Fortran Note:
1663:    The Fortran interface is slightly different from that given below.
1664:    See the Fortran chapter of the users manual and 
1665:    petsc/src/vec/examples for details.

1667:    Level: intermediate

1669: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
1670: @*/
1671: PetscErrorCode PETSCVEC_DLLEXPORT VecDestroyVecs(Vec vv[],PetscInt m)
1672: {

1679:   (*(*vv)->ops->destroyvecs)(vv,m);
1680:   return(0);
1681: }

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

1688:    Not Collective

1690:    Input Parameters:
1691: +  x - vector to insert in
1692: .  ni - number of elements to add
1693: .  ix - indices where to add
1694: .  y - array of values
1695: -  iora - either INSERT_VALUES or ADD_VALUES, where
1696:    ADD_VALUES adds values to any existing entries, and
1697:    INSERT_VALUES replaces existing entries with new values

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

1702:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1703:    options cannot be mixed without intervening calls to the assembly
1704:    routines.

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

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

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

1716:    Level: beginner

1718:    Concepts: vector^setting values

1720: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1721:            VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
1722: @*/
1723: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1724: {

1732:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1733:   (*x->ops->setvalues)(x,ni,ix,y,iora);
1734:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1735:   PetscObjectStateIncrease((PetscObject)x);
1736:   return(0);
1737: }

1741: /*@
1742:    VecGetValues - Gets values from certain locations of a vector. Currently 
1743:           can only get values on the same processor

1745:     Collective on Vec
1746:  
1747:    Input Parameters:
1748: +  x - vector to get values from
1749: .  ni - number of elements to get
1750: -  ix - indices where to get them from (in global 1d numbering)

1752:    Output Parameter:
1753: .   y - array of values

1755:    Notes: 
1756:    The user provides the allocated array y; it is NOT allocated in this routine

1758:    VecGetValues() gets y[i] = x[ix[i]], for i=0,...,ni-1.

1760:    VecAssemblyBegin() and VecAssemblyEnd()  MUST be called before calling this

1762:    VecGetValues() uses 0-based indices in Fortran as well as in C.

1764:    Level: beginner

1766:    Concepts: vector^getting values

1768: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
1769:            VecGetValue(), VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
1770: @*/
1771: PetscErrorCode PETSCVEC_DLLEXPORT VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
1772: {

1780:   (*x->ops->getvalues)(x,ni,ix,y);
1781:   return(0);
1782: }

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

1789:    Not Collective

1791:    Input Parameters:
1792: +  x - vector to insert in
1793: .  ni - number of blocks to add
1794: .  ix - indices where to add in block count, rather than element count
1795: .  y - array of values
1796: -  iora - either INSERT_VALUES or ADD_VALUES, where
1797:    ADD_VALUES adds values to any existing entries, and
1798:    INSERT_VALUES replaces existing entries with new values

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

1804:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
1805:    options cannot be mixed without intervening calls to the assembly
1806:    routines.

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

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

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

1818:    Level: intermediate

1820:    Concepts: vector^setting values blocked

1822: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1823:            VecSetValues()
1824: @*/
1825: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1826: {

1834:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1835:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1836:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1837:   PetscObjectStateIncrease((PetscObject)x);
1838:   return(0);
1839: }

1843: /*@
1844:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1845:    by the routine VecSetValuesLocal() to allow users to insert vector entries
1846:    using a local (per-processor) numbering.

1848:    Collective on Vec

1850:    Input Parameters:
1851: +  x - vector
1852: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1857:    Level: intermediate

1859:    Concepts: vector^setting values with local numbering

1861: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1862:            VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1863: @*/
1864: PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1865: {


1872:   if (x->mapping) {
1873:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1874:   }

1876:   if (x->ops->setlocaltoglobalmapping) {
1877:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1878:   } else {
1879:     x->mapping = mapping;
1880:     PetscObjectReference((PetscObject)mapping);
1881:   }
1882:   return(0);
1883: }

1887: /*@
1888:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1889:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1890:    using a local (per-processor) numbering.

1892:    Collective on Vec

1894:    Input Parameters:
1895: +  x - vector
1896: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1901:    Level: intermediate

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

1905: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1906:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1907: @*/
1908: PetscErrorCode PETSCVEC_DLLEXPORT VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1909: {


1916:   if (x->bmapping) {
1917:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1918:   }
1919:   x->bmapping = mapping;
1920:   PetscObjectReference((PetscObject)mapping);
1921:   return(0);
1922: }

1926: /*@
1927:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1928:    using a local ordering of the nodes. 

1930:    Not Collective

1932:    Input Parameters:
1933: +  x - vector to insert in
1934: .  ni - number of elements to add
1935: .  ix - indices where to add
1936: .  y - array of values
1937: -  iora - either INSERT_VALUES or ADD_VALUES, where
1938:    ADD_VALUES adds values to any existing entries, and
1939:    INSERT_VALUES replaces existing entries with new values

1941:    Level: intermediate

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

1946:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1947:    options cannot be mixed without intervening calls to the assembly
1948:    routines.

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

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

1955:    Concepts: vector^setting values with local numbering

1957: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1958:            VecSetValuesBlockedLocal()
1959: @*/
1960: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1961: {
1963:   PetscInt       lixp[128],*lix = lixp;


1971:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1972:   if (!x->ops->setvalueslocal) {
1973:     if (!x->mapping) {
1974:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1975:     }
1976:     if (ni > 128) {
1977:       PetscMalloc(ni*sizeof(PetscInt),&lix);
1978:     }
1979:     ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
1980:     (*x->ops->setvalues)(x,ni,lix,y,iora);
1981:     if (ni > 128) {
1982:       PetscFree(lix);
1983:     }
1984:   } else {
1985:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1986:   }
1987:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1988:   PetscObjectStateIncrease((PetscObject)x);
1989:   return(0);
1990: }

1994: /*@
1995:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1996:    using a local ordering of the nodes. 

1998:    Not Collective

2000:    Input Parameters:
2001: +  x - vector to insert in
2002: .  ni - number of blocks to add
2003: .  ix - indices where to add in block count, not element count
2004: .  y - array of values
2005: -  iora - either INSERT_VALUES or ADD_VALUES, where
2006:    ADD_VALUES adds values to any existing entries, and
2007:    INSERT_VALUES replaces existing entries with new values

2009:    Level: intermediate

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

2015:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
2016:    options cannot be mixed without intervening calls to the assembly
2017:    routines.

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

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


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

2027: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
2028:            VecSetLocalToGlobalMappingBlocked()
2029: @*/
2030: PetscErrorCode PETSCVEC_DLLEXPORT VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
2031: {
2033:   PetscInt       lixp[128],*lix = lixp;

2040:   if (!x->bmapping) {
2041:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
2042:   }
2043:   if (ni > 128) {
2044:     PetscMalloc(ni*sizeof(PetscInt),&lix);
2045:   }

2047:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
2048:   ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
2049:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
2050:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
2051:   if (ni > 128) {
2052:     PetscFree(lix);
2053:   }
2054:   PetscObjectStateIncrease((PetscObject)x);
2055:   return(0);
2056: }

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

2064:    Collective on Vec

2066:    Input Parameter:
2067: .  vec - the vector

2069:    Level: beginner

2071:    Concepts: assembly^vectors

2073: .seealso: VecAssemblyEnd(), VecSetValues()
2074: @*/
2075: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyBegin(Vec vec)
2076: {
2078:   PetscTruth     flg;


2084:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
2085:   if (flg) {
2086:     VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2087:   }

2089:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
2090:   if (vec->ops->assemblybegin) {
2091:     (*vec->ops->assemblybegin)(vec);
2092:   }
2093:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
2094:   PetscObjectStateIncrease((PetscObject)vec);
2095:   return(0);
2096: }

2100: /*@
2101:    VecAssemblyEnd - Completes assembling the vector.  This routine should
2102:    be called after VecAssemblyBegin().

2104:    Collective on Vec

2106:    Input Parameter:
2107: .  vec - the vector

2109:    Options Database Keys:
2110: +  -vec_view - Prints vector in ASCII format
2111: .  -vec_view_matlab - Prints vector in ASCII Matlab format to stdout
2112: .  -vec_view_matlab_file - Prints vector in Matlab format to matlaboutput.mat
2113: .  -vec_view_draw - Activates vector viewing using drawing tools
2114: .  -display <name> - Sets display name (default is host)
2115: .  -draw_pause <sec> - Sets number of seconds to pause after display
2116: -  -vec_view_socket - Activates vector viewing using a socket
2117:  
2118:    Level: beginner

2120: .seealso: VecAssemblyBegin(), VecSetValues()
2121: @*/
2122: PetscErrorCode PETSCVEC_DLLEXPORT VecAssemblyEnd(Vec vec)
2123: {
2125:   PetscTruth     flg;

2129:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
2131:   if (vec->ops->assemblyend) {
2132:     (*vec->ops->assemblyend)(vec);
2133:   }
2134:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
2135:   PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
2136:     PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
2137:     if (flg) {
2138:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2139:     }
2140:     PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
2141:     if (flg) {
2142:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
2143:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
2144:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
2145:     }
2146: #if defined(PETSC_HAVE_MATLAB)
2147:     PetscOptionsName("-vec_view_matlab_file","Print vector to matlaboutput.mat format Matlab can read","VecView",&flg);
2148:     if (flg) {
2149:       VecView(vec,PETSC_VIEWER_MATLAB_(vec->comm));
2150:     }
2151: #endif
2152: #if defined(PETSC_USE_SOCKET_VIEWER)
2153:     PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
2154:     if (flg) {
2155:       VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
2156:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
2157:     }
2158: #endif
2159:     PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
2160:     if (flg) {
2161:       VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
2162:       PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
2163:     }
2164:   PetscOptionsEnd();
2165:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
2166:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
2167:   PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
2168:   if (flg) {
2169:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
2170:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
2171:   }
2172:   PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
2173:   if (flg) {
2174:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
2175:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
2176:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
2177:   }
2178:   return(0);
2179: }


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

2188:    Collective on Vec

2190:    Input Parameters:
2191: +  nv - number of vectors
2192: .  x - one vector
2193: -  y - array of vectors.  Note that vectors are pointers

2195:    Output Parameter:
2196: .  val - array of the dot products

2198:    Notes for Users of Complex Numbers:
2199:    For complex vectors, VecMTDot() computes the indefinite form
2200: $      val = (x,y) = y^T x,
2201:    where y^T denotes the transpose of y.

2203:    Use VecMDot() for the inner product
2204: $      val = (x,y) = y^H x,
2205:    where y^H denotes the conjugate transpose of y.

2207:    Level: intermediate

2209:    Concepts: inner product^multiple
2210:    Concepts: vector^multiple inner products

2212: .seealso: VecMDot(), VecTDot()
2213: @*/
2214: PetscErrorCode PETSCVEC_DLLEXPORT VecMTDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
2215: {

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

2229:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
2230:   (*x->ops->mtdot)(nv,x,y,val);
2231:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
2232:   return(0);
2233: }

2237: /*@C
2238:    VecMDot - Computes vector multiple dot products. 

2240:    Collective on Vec

2242:    Input Parameters:
2243: +  nv - number of vectors
2244: .  x - one vector
2245: -  y - array of vectors. 

2247:    Output Parameter:
2248: .  val - array of the dot products

2250:    Notes for Users of Complex Numbers:
2251:    For complex vectors, VecMDot() computes 
2252: $     val = (x,y) = y^H x,
2253:    where y^H denotes the conjugate transpose of y.

2255:    Use VecMTDot() for the indefinite form
2256: $     val = (x,y) = y^T x,
2257:    where y^T denotes the transpose of y.

2259:    Level: intermediate

2261:    Concepts: inner product^multiple
2262:    Concepts: vector^multiple inner products

2264: .seealso: VecMTDot(), VecDot()
2265: @*/
2266: PetscErrorCode PETSCVEC_DLLEXPORT VecMDot(PetscInt nv,Vec x,const Vec y[],PetscScalar *val)
2267: {

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

2281:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
2282:   (*x->ops->mdot)(nv,x,y,val);
2283:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
2284:   return(0);
2285: }

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

2292:    Collective on Vec

2294:    Input Parameters:
2295: +  nv - number of scalars and x-vectors
2296: .  alpha - array of scalars
2297: .  y - one vector
2298: -  x - array of vectors

2300:    Level: intermediate

2302:    Concepts: BLAS

2304: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
2305: @*/
2306: PetscErrorCode PETSCVEC_DLLEXPORT VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec *x)
2307: {

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

2321:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
2322:   (*y->ops->maxpy)(y,nv,alpha,x);
2323:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
2324:   PetscObjectStateIncrease((PetscObject)y);
2325:   return(0);
2326: }

2328: /*MC
2329:    VecGetArray - Returns a pointer to a contiguous array that contains this 
2330:    processor's portion of the vector data. For the standard PETSc
2331:    vectors, VecGetArray() returns a pointer to the local data array and
2332:    does not use any copies. If the underlying vector data is not stored
2333:    in a contiquous array this routine will copy the data to a contiquous
2334:    array and return a pointer to that. You MUST call VecRestoreArray() 
2335:    when you no longer need access to the array.

2337:    Synopsis:
2338:    PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])

2340:    Not Collective

2342:    Input Parameter:
2343: .  x - the vector

2345:    Output Parameter:
2346: .  a - location to put pointer to the array

2348:    Fortran Note:
2349:    This routine is used differently from Fortran 77
2350: $    Vec         x
2351: $    PetscScalar x_array(1)
2352: $    PetscOffset i_x
2353: $    PetscErrorCode ierr
2354: $       call VecGetArray(x,x_array,i_x,ierr)
2355: $
2356: $   Access first local entry in vector with
2357: $      value = x_array(i_x + 1)
2358: $
2359: $      ...... other code
2360: $       call VecRestoreArray(x,x_array,i_x,ierr)
2361:    For Fortran 90 see VecGetArrayF90()

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

2366:    Level: beginner

2368:    Concepts: vector^accessing local values

2370: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
2371: M*/
2374: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
2375: {

2382:   (*x->ops->getarray)(x,a);
2383:   return(0);
2384: }


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

2394:    Not Collective

2396:    Input Parameter:
2397: +  x - the vectors
2398: -  n - the number of vectors

2400:    Output Parameter:
2401: .  a - location to put pointer to the array

2403:    Fortran Note:
2404:    This routine is not supported in Fortran.

2406:    Level: intermediate

2408: .seealso: VecGetArray(), VecRestoreArrays()
2409: @*/
2410: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2411: {
2413:   PetscInt       i;
2414:   PetscScalar    **q;

2420:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
2421:   PetscMalloc(n*sizeof(PetscScalar*),&q);
2422:   for (i=0; i<n; ++i) {
2423:     VecGetArray(x[i],&q[i]);
2424:   }
2425:   *a = q;
2426:   return(0);
2427: }

2431: /*@C
2432:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
2433:    has been called.

2435:    Not Collective

2437:    Input Parameters:
2438: +  x - the vector
2439: .  n - the number of vectors
2440: -  a - location of pointer to arrays obtained from VecGetArrays()

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

2448:    Fortran Note:
2449:    This routine is not supported in Fortran.

2451:    Level: intermediate

2453: .seealso: VecGetArrays(), VecRestoreArray()
2454: @*/
2455: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
2456: {
2458:   PetscInt       i;
2459:   PetscScalar    **q = *a;


2466:   for(i=0;i<n;++i) {
2467:     VecRestoreArray(x[i],&q[i]);
2468:  }
2469:   PetscFree(q);
2470:   return(0);
2471: }

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

2476:    Not Collective

2478:    Synopsis:
2479:    PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])

2481:    Input Parameters:
2482: +  x - the vector
2483: -  a - location of pointer to array obtained from VecGetArray()

2485:    Level: beginner

2487:    Notes:
2488:    For regular PETSc vectors this routine does not involve any copies. For
2489:    any special vectors that do not store local vector data in a contiguous
2490:    array, this routine will copy the data back into the underlying 
2491:    vector data structure from the array obtained with VecGetArray().

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

2497:    Fortran Note:
2498:    This routine is used differently from Fortran 77
2499: $    Vec         x
2500: $    PetscScalar x_array(1)
2501: $    PetscOffset i_x
2502: $    PetscErrorCode ierr
2503: $       call VecGetArray(x,x_array,i_x,ierr)
2504: $
2505: $   Access first local entry in vector with
2506: $      value = x_array(i_x + 1)
2507: $
2508: $      ...... other code
2509: $       call VecRestoreArray(x,x_array,i_x,ierr)

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

2515: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2516: M*/
2519: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
2520: {

2527: #if defined(PETSC_USE_DEBUG)
2528:   CHKMEMQ;
2529: #endif
2530:   if (x->ops->restorearray) {
2531:     (*x->ops->restorearray)(x,a);
2532:   }
2533:   PetscObjectStateIncrease((PetscObject)x);
2534:   return(0);
2535: }

2537: #undef  __FUNCT__
2539: /*@
2540:   VecViewFromOptions - This function visualizes the vector based upon user options.

2542:   Collective on Vec

2544:   Input Parameters:
2545: . vec   - The vector
2546: . title - The title

2548:   Level: intermediate

2550: .keywords: Vec, view, options, database
2551: .seealso: VecSetFromOptions(), VecView()
2552: @*/
2553: PetscErrorCode PETSCVEC_DLLEXPORT VecViewFromOptions(Vec vec, char *title)
2554: {
2555:   PetscViewer    viewer;
2556:   PetscDraw      draw;
2557:   PetscTruth     opt;
2558:   char           *titleStr;
2559:   char           typeName[1024];
2560:   char           fileName[PETSC_MAX_PATH_LEN];
2561:   size_t         len;

2565:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2566:   if (opt) {
2567:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2568:     PetscStrlen(typeName, &len);
2569:     if (len > 0) {
2570:       PetscViewerCreate(vec->comm, &viewer);
2571:       PetscViewerSetType(viewer, typeName);
2572:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2573:       if (opt) {
2574:         PetscViewerSetFilename(viewer, fileName);
2575:       } else {
2576:         PetscViewerSetFilename(viewer, vec->name);
2577:       }
2578:       VecView(vec, viewer);
2579:       PetscViewerFlush(viewer);
2580:       PetscViewerDestroy(viewer);
2581:     } else {
2582:       VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2583:     }
2584:   }
2585:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2586:   if (opt) {
2587:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2588:     PetscViewerDrawGetDraw(viewer, 0, &draw);
2589:     if (title) {
2590:       titleStr = title;
2591:     } else {
2592:       PetscObjectName((PetscObject) vec);
2593:       titleStr = vec->name;
2594:     }
2595:     PetscDrawSetTitle(draw, titleStr);
2596:     VecView(vec, viewer);
2597:     PetscViewerFlush(viewer);
2598:     PetscDrawPause(draw);
2599:     PetscViewerDestroy(viewer);
2600:   }
2601:   return(0);
2602: }

2606: /*@C
2607:    VecView - Views a vector object. 

2609:    Collective on Vec

2611:    Input Parameters:
2612: +  v - the vector
2613: -  viewer - an optional visualization context

2615:    Notes:
2616:    The available visualization contexts include
2617: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
2618: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2619:          output where only the first processor opens
2620:          the file.  All other processors send their 
2621:          data to the first processor to print. 

2623:    You can change the format the vector is printed using the 
2624:    option PetscViewerSetFormat().

2626:    The user can open alternative visualization contexts with
2627: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
2628: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
2629:          specified file; corresponding input uses VecLoad()
2630: .    PetscViewerDrawOpen() - Outputs vector to an X window display
2631: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

2633:    The user can call PetscViewerSetFormat() to specify the output
2634:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2635:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
2636: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2637: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2638: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2639: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
2640:          format common among all vector types

2642:    Level: beginner

2644:    Concepts: vector^printing
2645:    Concepts: vector^saving to disk

2647: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2648:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2649:           PetscRealView(), PetscScalarView(), PetscIntView()
2650: @*/
2651: PetscErrorCode PETSCVEC_DLLEXPORT VecView(Vec vec,PetscViewer viewer)
2652: {
2653:   PetscErrorCode    ierr;
2654:   PetscViewerFormat format;

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

2664:   /*
2665:      Check if default viewer has been overridden, but user request it anyways
2666:   */
2667:   PetscViewerGetFormat(viewer,&format);
2668:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2669:     PetscViewerPopFormat(viewer);
2670:     (*vec->ops->viewnative)(vec,viewer);
2671:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2672:   } else {
2673:     (*vec->ops->view)(vec,viewer);
2674:   }
2675:   return(0);
2676: }

2680: /*@
2681:    VecGetSize - Returns the global number of elements of the vector.

2683:    Not Collective

2685:    Input Parameter:
2686: .  x - the vector

2688:    Output Parameters:
2689: .  size - the global length of the vector

2691:    Level: beginner

2693:    Concepts: vector^local size

2695: .seealso: VecGetLocalSize()
2696: @*/
2697: PetscErrorCode PETSCVEC_DLLEXPORT VecGetSize(Vec x,PetscInt *size)
2698: {

2705:   (*x->ops->getsize)(x,size);
2706:   return(0);
2707: }

2711: /*@
2712:    VecGetLocalSize - Returns the number of elements of the vector stored 
2713:    in local memory. This routine may be implementation dependent, so use 
2714:    with care.

2716:    Not Collective

2718:    Input Parameter:
2719: .  x - the vector

2721:    Output Parameter:
2722: .  size - the length of the local piece of the vector

2724:    Level: beginner

2726:    Concepts: vector^size

2728: .seealso: VecGetSize()
2729: @*/
2730: PetscErrorCode PETSCVEC_DLLEXPORT VecGetLocalSize(Vec x,PetscInt *size)
2731: {

2738:   (*x->ops->getlocalsize)(x,size);
2739:   return(0);
2740: }

2744: /*@C
2745:    VecGetOwnershipRange - Returns the range of indices owned by 
2746:    this processor, assuming that the vectors are laid out with the
2747:    first n1 elements on the first processor, next n2 elements on the
2748:    second, etc.  For certain parallel layouts this range may not be 
2749:    well defined. 

2751:    Not Collective

2753:    Input Parameter:
2754: .  x - the vector

2756:    Output Parameters:
2757: +  low - the first local element, pass in PETSC_NULL if not interested
2758: -  high - one more than the last local element, pass in PETSC_NULL if not interested

2760:    Note:
2761:    The high argument is one more than the last element stored locally.

2763:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

2765:    Level: beginner

2767:    Concepts: ownership^of vectors
2768:    Concepts: vector^ownership of elements

2770: @*/
2771: PetscErrorCode PETSCVEC_DLLEXPORT VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
2772: {

2780:   PetscMapGetLocalRange(x->map,low,high);
2781:   return(0);
2782: }

2786: /*@C
2787:    VecGetPetscMap - Returns the map associated with the vector

2789:    Not Collective

2791:    Input Parameter:
2792: .  x - the vector

2794:    Output Parameters:
2795: .  map - the map

2797:    Level: developer

2799: @*/
2800: PetscErrorCode PETSCVEC_DLLEXPORT VecGetPetscMap(Vec x,PetscMap *map)
2801: {
2806:   *map = x->map;
2807:   return(0);
2808: }

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

2815:    Collective on Vec

2817:    Input Parameter:
2818: +  x - the vector
2819: -  op - the option

2821:    Supported Options:
2822: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
2823:       entries destined to be stored on a seperate processor. This can be used
2824:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
2825:       that you have only used VecSetValues() to set local elements
2826: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

2828:    Level: intermediate

2830: @*/
2831: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOption(Vec x,VecOption op)
2832: {

2838:   if (x->ops->setoption) {
2839:     (*x->ops->setoption)(x,op);
2840:   }
2841:   return(0);
2842: }

2846: /* Default routines for obtaining and releasing; */
2847: /* may be used by any implementation */
2848: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
2849: {
2851:   PetscInt       i;

2856:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2857:   PetscMalloc(m*sizeof(Vec*),V);
2858:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2859:   return(0);
2860: }

2864: PetscErrorCode VecDestroyVecs_Default(Vec v[], PetscInt m)
2865: {
2867:   PetscInt       i;

2871:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
2872:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
2873:   PetscFree(v);
2874:   return(0);
2875: }

2879: /*@
2880:    VecPlaceArray - Allows one to replace the array in a vector with an
2881:    array provided by the user. This is useful to avoid copying an array
2882:    into a vector.

2884:    Not Collective

2886:    Input Parameters:
2887: +  vec - the vector
2888: -  array - the array

2890:    Notes:
2891:    You can return to the original array with a call to VecResetArray()

2893:    Level: developer

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

2897: @*/
2898: PetscErrorCode PETSCVEC_DLLEXPORT VecPlaceArray(Vec vec,const PetscScalar array[])
2899: {

2906:   if (vec->ops->placearray) {
2907:     (*vec->ops->placearray)(vec,array);
2908:   } else {
2909:     SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
2910:   }
2911:   PetscObjectStateIncrease((PetscObject)vec);
2912:   return(0);
2913: }

2917: /*@
2918:    VecResetArray - Resets a vector to use its default memory. Call this 
2919:    after the use of VecPlaceArray().

2921:    Not Collective

2923:    Input Parameters:
2924: .  vec - the vector

2926:    Level: developer

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

2930: @*/
2931: PetscErrorCode PETSCVEC_DLLEXPORT VecResetArray(Vec vec)
2932: {

2938:   if (vec->ops->resetarray) {
2939:     (*vec->ops->resetarray)(vec);
2940:   } else {
2941:     SETERRQ(PETSC_ERR_SUP,"Cannot reset array in this type of vector");
2942:   }
2943:   PetscObjectStateIncrease((PetscObject)vec);
2944:   return(0);
2945: }

2949: /*@C
2950:    VecReplaceArray - Allows one to replace the array in a vector with an
2951:    array provided by the user. This is useful to avoid copying an array
2952:    into a vector.

2954:    Not Collective

2956:    Input Parameters:
2957: +  vec - the vector
2958: -  array - the array

2960:    Notes:
2961:    This permanently replaces the array and frees the memory associated
2962:    with the old array.

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

2967:    Not supported from Fortran

2969:    Level: developer

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

2973: @*/
2974: PetscErrorCode PETSCVEC_DLLEXPORT VecReplaceArray(Vec vec,const PetscScalar array[])
2975: {

2981:   if (vec->ops->replacearray) {
2982:     (*vec->ops->replacearray)(vec,array);
2983:  } else {
2984:     SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
2985:   }
2986:   PetscObjectStateIncrease((PetscObject)vec);
2987:   return(0);
2988: }

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

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

2997:     Collective on Vec

2999:     Input Parameters:
3000: +   x - a vector to mimic
3001: -   n - the number of vectors to obtain

3003:     Output Parameters:
3004: +   y - Fortran90 pointer to the array of vectors
3005: -   ierr - error code

3007:     Example of Usage: 
3008: .vb
3009:     Vec x
3010:     Vec, pointer :: y(:)
3011:     ....
3012:     call VecDuplicateVecsF90(x,2,y,ierr)
3013:     call VecSet(y(2),alpha,ierr)
3014:     call VecSet(y(2),alpha,ierr)
3015:     ....
3016:     call VecDestroyVecsF90(y,2,ierr)
3017: .ve

3019:     Notes:
3020:     Not yet supported for all F90 compilers

3022:     Use VecDestroyVecsF90() to free the space.

3024:     Level: beginner

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

3028: M*/

3030: /*MC
3031:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
3032:     VecGetArrayF90().

3034:     Synopsis:
3035:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

3037:     Not collective

3039:     Input Parameters:
3040: +   x - vector
3041: -   xx_v - the Fortran90 pointer to the array

3043:     Output Parameter:
3044: .   ierr - error code

3046:     Example of Usage: 
3047: .vb
3048:     PetscScalar, pointer :: xx_v(:)
3049:     ....
3050:     call VecGetArrayF90(x,xx_v,ierr)
3051:     a = xx_v(3)
3052:     call VecRestoreArrayF90(x,xx_v,ierr)
3053: .ve
3054:    
3055:     Notes:
3056:     Not yet supported for all F90 compilers

3058:     Level: beginner

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

3062: M*/

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

3067:     Synopsis:
3068:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

3070:     Input Parameters:
3071: +   x - pointer to array of vector pointers
3072: -   n - the number of vectors previously obtained

3074:     Output Parameter:
3075: .   ierr - error code

3077:     Notes:
3078:     Not yet supported for all F90 compilers

3080:     Level: beginner

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

3084: M*/

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

3092:     Synopsis:
3093:     VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

3095:     Not Collective 

3097:     Input Parameter:
3098: .   x - vector

3100:     Output Parameters:
3101: +   xx_v - the Fortran90 pointer to the array
3102: -   ierr - error code

3104:     Example of Usage: 
3105: .vb
3106:     PetscScalar, pointer :: xx_v(:)
3107:     ....
3108:     call VecGetArrayF90(x,xx_v,ierr)
3109:     a = xx_v(3)
3110:     call VecRestoreArrayF90(x,xx_v,ierr)
3111: .ve

3113:     Notes:
3114:     Not yet supported for all F90 compilers

3116:     Level: beginner

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

3120: M*/

3124: /*@C 
3125:   VecLoadIntoVector - Loads a vector that has been stored in binary format
3126:   with VecView().

3128:   Collective on PetscViewer 

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

3134:   Level: intermediate

3136:   Notes:
3137:   The input file must contain the full global vector, as
3138:   written by the routine VecView().

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

3142:   Notes for advanced users:
3143:   Most users should not need to know the details of the binary storage
3144:   format, since VecLoad() and VecView() completely hide these details.
3145:   But for anyone who's interested, the standard binary matrix storage
3146:   format is
3147: .vb
3148:      int    VEC_FILE_COOKIE
3149:      int    number of rows
3150:      PetscScalar *values of all nonzeros
3151: .ve

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

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

3166:    Concepts: vector^loading from file

3168: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
3169: @*/
3170: PetscErrorCode PETSCVEC_DLLEXPORT VecLoadIntoVector(PetscViewer viewer,Vec vec)
3171: {

3178:   if (!vec->ops->loadintovector) {
3179:     SETERRQ(PETSC_ERR_SUP,"Vector does not support load");
3180:   }
3181:   (*vec->ops->loadintovector)(viewer,vec);
3182:   PetscObjectStateIncrease((PetscObject)vec);
3183:   return(0);
3184: }

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

3191:    Collective on Vec

3193:    Input Parameter:
3194: .  v - the vector 

3196:    Output Parameter:
3197: .  v - the vector reciprocal

3199:    Level: intermediate

3201:    Concepts: vector^reciprocal

3203: @*/
3204: PetscErrorCode PETSCVEC_DLLEXPORT VecReciprocal(Vec vec)
3205: {

3211:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3212:   if (!vec->ops->reciprocal) {
3213:     SETERRQ(PETSC_ERR_SUP,"Vector does not support reciprocal operation");
3214:   }
3215:   (*vec->ops->reciprocal)(vec);
3216:   PetscObjectStateIncrease((PetscObject)vec);
3217:   return(0);
3218: }

3222: PetscErrorCode PETSCVEC_DLLEXPORT VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
3223: {
3226:   /* save the native version of the viewer */
3227:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
3228:     vec->ops->viewnative = vec->ops->view;
3229:   }
3230:   (((void(**)(void))vec->ops)[(int)op]) = f;
3231:   return(0);
3232: }

3236: /*@
3237:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
3238:    used during the assembly process to store values that belong to 
3239:    other processors.

3241:    Collective on Vec

3243:    Input Parameters:
3244: +  vec   - the vector
3245: .  size  - the initial size of the stash.
3246: -  bsize - the initial size of the block-stash(if used).

3248:    Options Database Keys:
3249: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
3250: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

3252:    Level: intermediate

3254:    Notes: 
3255:      The block-stash is used for values set with VecSetValuesBlocked() while
3256:      the stash is used for values set with VecSetValues()

3258:      Run with the option -log_info and look for output of the form
3259:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
3260:      to determine the appropriate value, MM, to use for size and 
3261:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
3262:      to determine the value, BMM to use for bsize

3264:    Concepts: vector^stash
3265:    Concepts: stash^vector

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

3269: @*/
3270: PetscErrorCode PETSCVEC_DLLEXPORT VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
3271: {

3276:   VecStashSetInitialSize_Private(&vec->stash,size);
3277:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
3278:   return(0);
3279: }

3283: /*@
3284:    VecStashView - Prints the entries in the vector stash and block stash.

3286:    Collective on Vec

3288:    Input Parameters:
3289: +  vec   - the vector
3290: -  viewer - the viewer

3292:    Level: advanced

3294:    Concepts: vector^stash
3295:    Concepts: stash^vector

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

3299: @*/
3300: PetscErrorCode PETSCVEC_DLLEXPORT VecStashView(Vec v,PetscViewer viewer)
3301: {
3303:   PetscMPIInt    rank;
3304:   PetscInt       i,j;
3305:   PetscTruth     match;
3306:   VecStash       *s;
3307:   PetscScalar    val;


3314:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
3315:   if (!match) SETERRQ1(PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
3316:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
3317:   MPI_Comm_rank(v->comm,&rank);
3318:   s = &v->bstash;

3320:   /* print block stash */
3321:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
3322:   for (i=0; i<s->n; i++) {
3323:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
3324:     for (j=0; j<s->bs; j++) {
3325:       val = s->array[i*s->bs+j];
3326: #if defined(PETSC_USE_COMPLEX)
3327:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
3328: #else
3329:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
3330: #endif
3331:     }
3332:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
3333:   }
3334:   PetscViewerFlush(viewer);

3336:   s = &v->stash;

3338:   /* print basic stash */
3339:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
3340:   for (i=0; i<s->n; i++) {
3341:     val = s->array[i];
3342: #if defined(PETSC_USE_COMPLEX)
3343:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
3344: #else
3345:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
3346: #endif
3347:   }
3348:   PetscViewerFlush(viewer);

3350:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
3351:   return(0);
3352: }

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

3361:    Not Collective

3363:    Input Parameter:
3364: +  x - the vector
3365: .  m - first dimension of two dimensional array
3366: .  n - second dimension of two dimensional array
3367: .  mstart - first index you will use in first coordinate direction (often 0)
3368: -  nstart - first index in the second coordinate direction (often 0)

3370:    Output Parameter:
3371: .  a - location to put pointer to the array

3373:    Level: beginner

3375:   Notes:
3376:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
3377:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3378:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3379:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
3380:    
3381:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3385: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3386:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3387:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3388: @*/
3389: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3390: {
3392:   PetscInt       i,N;
3393:   PetscScalar    *aa;

3399:   VecGetLocalSize(x,&N);
3400:   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);
3401:   VecGetArray(x,&aa);

3403:   PetscMalloc(m*sizeof(PetscScalar*),a);
3404:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
3405:   *a -= mstart;
3406:   return(0);
3407: }

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

3414:    Not Collective

3416:    Input Parameters:
3417: +  x - the vector
3418: .  m - first dimension of two dimensional array
3419: .  n - second dimension of the two dimensional array
3420: .  mstart - first index you will use in first coordinate direction (often 0)
3421: .  nstart - first index in the second coordinate direction (often 0)
3422: -  a - location of pointer to array obtained from VecGetArray2d()

3424:    Level: beginner

3426:    Notes:
3427:    For regular PETSc vectors this routine does not involve any copies. For
3428:    any special vectors that do not store local vector data in a contiguous
3429:    array, this routine will copy the data back into the underlying 
3430:    vector data structure from the array obtained with VecGetArray().

3432:    This routine actually zeros out the a pointer. 

3434: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3435:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3436:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3437: @*/
3438: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
3439: {
3441:   void           *dummy;

3447:   dummy = (void*)(*a + mstart);
3448:   PetscFree(dummy);
3449:   VecRestoreArray(x,PETSC_NULL);
3450:   return(0);
3451: }

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

3460:    Not Collective

3462:    Input Parameter:
3463: +  x - the vector
3464: .  m - first dimension of two dimensional array
3465: -  mstart - first index you will use in first coordinate direction (often 0)

3467:    Output Parameter:
3468: .  a - location to put pointer to the array

3470:    Level: beginner

3472:   Notes:
3473:    For a vector obtained from DACreateLocalVector() mstart are likely
3474:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3475:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
3476:    
3477:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

3479: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3480:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3481:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3482: @*/
3483: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3484: {
3486:   PetscInt       N;

3492:   VecGetLocalSize(x,&N);
3493:   if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
3494:   VecGetArray(x,a);
3495:   *a  -= mstart;
3496:   return(0);
3497: }

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

3504:    Not Collective

3506:    Input Parameters:
3507: +  x - the vector
3508: .  m - first dimension of two dimensional array
3509: .  mstart - first index you will use in first coordinate direction (often 0)
3510: -  a - location of pointer to array obtained from VecGetArray21()

3512:    Level: beginner

3514:    Notes:
3515:    For regular PETSc vectors this routine does not involve any copies. For
3516:    any special vectors that do not store local vector data in a contiguous
3517:    array, this routine will copy the data back into the underlying 
3518:    vector data structure from the array obtained with VecGetArray1d().

3520:    This routine actually zeros out the a pointer. 

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

3524: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3525:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3526:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3527: @*/
3528: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
3529: {

3535:   VecRestoreArray(x,PETSC_NULL);
3536:   return(0);
3537: }

3541: /*@
3542:    VecConjugate - Conjugates a vector.

3544:    Collective on Vec

3546:    Input Parameters:
3547: .  x - the vector

3549:    Level: intermediate

3551:    Concepts: vector^conjugate

3553: @*/
3554: PetscErrorCode PETSCVEC_DLLEXPORT VecConjugate(Vec x)
3555: {
3556: #ifdef PETSC_USE_COMPLEX

3562:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
3563:   (*x->ops->conjugate)(x);
3564:   /* we need to copy norms here */
3565:   PetscObjectStateIncrease((PetscObject)x);
3566:   return(0);
3567: #else
3568:   return(0);
3569: #endif
3570: }

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

3579:    Not Collective

3581:    Input Parameter:
3582: +  x - the vector
3583: .  m - first dimension of three dimensional array
3584: .  n - second dimension of three dimensional array
3585: .  p - third dimension of three dimensional array
3586: .  mstart - first index you will use in first coordinate direction (often 0)
3587: .  nstart - first index in the second coordinate direction (often 0)
3588: -  pstart - first index in the third coordinate direction (often 0)

3590:    Output Parameter:
3591: .  a - location to put pointer to the array

3593:    Level: beginner

3595:   Notes:
3596:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3597:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3598:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3599:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3600:    
3601:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3605: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3606:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3607:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3608: @*/
3609: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3610: {
3612:   PetscInt       i,N,j;
3613:   PetscScalar    *aa,**b;

3619:   VecGetLocalSize(x,&N);
3620:   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);
3621:   VecGetArray(x,&aa);

3623:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3624:   b    = (PetscScalar **)((*a) + m);
3625:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
3626:   for (i=0; i<m; i++) {
3627:     for (j=0; j<n; j++) {
3628:       b[i*n+j] = aa + i*n*p + j*p - pstart;
3629:     }
3630:   }
3631:   *a -= mstart;
3632:   return(0);
3633: }

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

3640:    Not Collective

3642:    Input Parameters:
3643: +  x - the vector
3644: .  m - first dimension of three dimensional array
3645: .  n - second dimension of the three dimensional array
3646: .  p - third dimension of the three dimensional array
3647: .  mstart - first index you will use in first coordinate direction (often 0)
3648: .  nstart - first index in the second coordinate direction (often 0)
3649: .  pstart - first index in the third coordinate direction (often 0)
3650: -  a - location of pointer to array obtained from VecGetArray3d()

3652:    Level: beginner

3654:    Notes:
3655:    For regular PETSc vectors this routine does not involve any copies. For
3656:    any special vectors that do not store local vector data in a contiguous
3657:    array, this routine will copy the data back into the underlying 
3658:    vector data structure from the array obtained with VecGetArray().

3660:    This routine actually zeros out the a pointer. 

3662: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3663:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3664:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3665: @*/
3666: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
3667: {
3669:   void           *dummy;

3675:   dummy = (void*)(*a + mstart);
3676:   PetscFree(dummy);
3677:   VecRestoreArray(x,PETSC_NULL);
3678:   return(0);
3679: }

3683: /*@C
3684:    VecGetArray4d - Returns a pointer to a 4d contiguous array that contains this 
3685:    processor's portion of the vector data.  You MUST call VecRestoreArray4d() 
3686:    when you no longer need access to the array.

3688:    Not Collective

3690:    Input Parameter:
3691: +  x - the vector
3692: .  m - first dimension of four dimensional array
3693: .  n - second dimension of four dimensional array
3694: .  p - third dimension of four dimensional array
3695: .  q - fourth dimension of four dimensional array
3696: .  mstart - first index you will use in first coordinate direction (often 0)
3697: .  nstart - first index in the second coordinate direction (often 0)
3698: .  pstart - first index in the third coordinate direction (often 0)
3699: -  qstart - first index in the fourth coordinate direction (often 0)

3701:    Output Parameter:
3702: .  a - location to put pointer to the array

3704:    Level: beginner

3706:   Notes:
3707:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3708:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3709:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3710:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3711:    
3712:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3716: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3717:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3718:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3719: @*/
3720: PetscErrorCode PETSCVEC_DLLEXPORT VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3721: {
3723:   PetscInt       i,N,j,k;
3724:   PetscScalar    *aa,***b,**c;

3730:   VecGetLocalSize(x,&N);
3731:   if (m*n*p*q != N) SETERRQ5(PETSC_ERR_ARG_INCOMP,"Local array size %D does not match 4d array dimensions %D by %D by %D by %D",N,m,n,p,q);
3732:   VecGetArray(x,&aa);

3734:   PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
3735:   b    = (PetscScalar ***)((*a) + m);
3736:   c    = (PetscScalar **)(b + m*n);
3737:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
3738:   for (i=0; i<m; i++) {
3739:     for (j=0; j<n; j++) {
3740:       b[i*n+j] = c + i*n*p + j*p - pstart;
3741:     }
3742:   }
3743:   for (i=0; i<m; i++) {
3744:     for (j=0; j<n; j++) {
3745:       for (k=0; k<p; k++) {
3746:         c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
3747:       }
3748:     }
3749:   }
3750:   *a -= mstart;
3751:   return(0);
3752: }

3756: /*@C
3757:    VecRestoreArray4d - Restores a vector after VecGetArray3d() has been called.

3759:    Not Collective

3761:    Input Parameters:
3762: +  x - the vector
3763: .  m - first dimension of four dimensional array
3764: .  n - second dimension of the four dimensional array
3765: .  p - third dimension of the four dimensional array
3766: .  q - fourth dimension of the four dimensional array
3767: .  mstart - first index you will use in first coordinate direction (often 0)
3768: .  nstart - first index in the second coordinate direction (often 0)
3769: .  pstart - first index in the third coordinate direction (often 0)
3770: .  qstart - first index in the fourth coordinate direction (often 0)
3771: -  a - location of pointer to array obtained from VecGetArray4d()

3773:    Level: beginner

3775:    Notes:
3776:    For regular PETSc vectors this routine does not involve any copies. For
3777:    any special vectors that do not store local vector data in a contiguous
3778:    array, this routine will copy the data back into the underlying 
3779:    vector data structure from the array obtained with VecGetArray().

3781:    This routine actually zeros out the a pointer. 

3783: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3784:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3785:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3786: @*/
3787: PetscErrorCode PETSCVEC_DLLEXPORT VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
3788: {
3790:   void           *dummy;

3796:   dummy = (void*)(*a + mstart);
3797:   PetscFree(dummy);
3798:   VecRestoreArray(x,PETSC_NULL);
3799:   return(0);
3800: }

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

3809:     Not collective

3811:    Input Parameter:
3812: .   vec - the vector

3814:    Output Parameters:
3815: +   nstash   - the size of the stash
3816: .   reallocs - the number of additional mallocs incurred.
3817: .   bnstash   - the size of the block stash
3818: -   breallocs - the number of additional mallocs incurred.in the block stash
3819:  
3820:    Level: advanced

3822: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()
3823:   
3824: @*/
3825: PetscErrorCode PETSCVEC_DLLEXPORT VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *brealloc)
3826: {
3829:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
3830:   VecStashGetInfo_Private(&vec->bstash,nstash,reallocs);
3831:   return(0);
3832: }