Actual source code: vector.c

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

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

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

 21:   Collective on Vec

 23:   Input Parameter:
 24: . vec - The vector

 26:   Level: intermediate

 28: .keywords: Vec, set, options, database, type
 29: .seealso: VecSetFromOptions(), VecSetType()
 30: */
 31: static int VecSetTypeFromOptions_Private(Vec vec)
 32: {
 33:   PetscTruth opt;
 34:   char      *defaultType;
 35:   char       typeName[256];
 36:   int        numProcs;
 37:   int        ierr;

 40:   if (vec->type_name != PETSC_NULL) {
 41:     defaultType = vec->type_name;
 42:   } else {
 43:     MPI_Comm_size(vec->comm, &numProcs);
 44:     if (numProcs > 1) {
 45:       defaultType = VECMPI;
 46:     } else {
 47:       defaultType = VECSEQ;
 48:     }
 49:   }

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

 66: /*@C
 67:   VecSetFromOptions - Configures the vector from the options database.

 69:   Collective on Vec

 71:   Input Parameter:
 72: . vec - The vector

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

 77:   Level: beginner

 79:   Concepts: vectors^setting options
 80:   Concepts: vectors^setting type

 82: .keywords: Vec, set, options, database
 83: .seealso: VecCreate(), VecPrintHelp(), VechSetOptionsPrefix()
 84: @*/
 85: int VecSetFromOptions(Vec vec)
 86: {
 87:   PetscTruth opt;
 88:   int        ierr;


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

 95:   /* Handle generic vector options */
 96:   PetscOptionsHasName(PETSC_NULL, "-help", &opt);
 97:   if (opt == PETSC_TRUE) {
 98:     VecPrintHelp(vec);
 99:   }

101:   /* Handle vector type options */
102:   VecSetTypeFromOptions_Private(vec);

104:   /* Handle specific vector options */
105:   if (vec->ops->setfromoptions != PETSC_NULL) {
106:     (*vec->ops->setfromoptions)(vec);
107:   }
108:   PetscOptionsEnd();

110: #if defined(__cplusplus) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE) && defined(PETSC_HAVE_CXX_NAMESPACE)
111:   VecESISetFromOptions(vec);
112: #endif

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

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

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

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

129:   Level: intermediate

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

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

146:   Collective on Vec

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

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

157:   Level: intermediate

159: .seealso: VecGetSize(), PetscSplitOwnership()
160: @*/
161: int VecSetSizes(Vec v, int n, int N)
162: {
165:   v->n = n;
166:   v->N = N;
167:   return(0);
168: }

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

176:    Collective on Vec

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

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

185:    Level: advanced

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

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

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

213:    Collective on Vec

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

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

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

224:    Level: advanced

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

228:    Concepts: vector^block size
229:    Concepts: block^vector

231: @*/
232: int VecGetBlockSize(Vec v,int *bs)
233: {
236:   *bs = v->bs;
237:   return(0);
238: }

242: /*@
243:    VecValid - Checks whether a vector object is valid.

245:    Not Collective

247:    Input Parameter:
248: .  v - the object to check

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

254:    Level: developer

256: @*/
257: int VecValid(Vec v,PetscTruth *flg)
258: {
261:   if (!v)                           *flg = PETSC_FALSE;
262:   else if (v->cookie != VEC_COOKIE) *flg = PETSC_FALSE;
263:   else                              *flg = PETSC_TRUE;
264:   return(0);
265: }

269: /*@
270:    VecDot - Computes the vector dot product.

272:    Collective on Vec

274:    Input Parameters:
275: .  x, y - the vectors

277:    Output Parameter:
278: .  alpha - the dot product

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

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

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

295:    Level: intermediate

297:    Concepts: inner product
298:    Concepts: vector^inner product

300: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
301: @*/
302: int VecDot(Vec x,Vec y,PetscScalar *val)
303: {

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

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

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

338:    Collective on Vec

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

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

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

354:    Level: intermediate

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

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

367:    Concepts: norm
368:    Concepts: vector^norm

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

373: @*/
374: int VecNorm(Vec x,NormType type,PetscReal *val)
375: {

381:   if ((type == NORM_2) && (x->normvalid)) {
382:     *val = x->normcurrent;
383:     return(0);
384:   }
385:   else {
386:     PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,x->comm);
387:     (*x->ops->norm)(x,type,val);
388:     PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,x->comm);
389:   }
390:   /*
391:      The next block is for incremental debugging
392:   */
393:   if (PetscCompare) {
394:     int flag;
395:     MPI_Comm_compare(PETSC_COMM_WORLD,x->comm,&flag);
396:     if (flag != MPI_UNEQUAL) {
397:       PetscCompareDouble(*val);
398:     }
399:   }
400:   if (type == NORM_2) {
401:     x->normcurrent = *val;
402:     x->normvalid   = PETSC_TRUE;
403:   }
404:   return(0);
405: }

409: /*@
410:    VecNormalize - Normalizes a vector by 2-norm. 

412:    Collective on Vec

414:    Input Parameters:
415: +  x - the vector

417:    Output Parameter:
418: .  x - the normalized vector
419: -  val - the vector norm before normalization

421:    Level: intermediate

423:    Concepts: vector^normalizing
424:    Concepts: normalizing^vector

426: @*/
427: int VecNormalize (Vec x,PetscReal *val)
428: {

435:   PetscLogEventBegin(VEC_Normalize,x,0,0,0);
436:   VecNorm(x,NORM_2,val);
437:   if (*val == 0.0) {
438:     PetscLogInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm");
439:   } else {
440:     PetscScalar tmp = 1.0/(*val);
441:     VecScale(&tmp,x);
442:     x->normcurrent = 1.0;
443:     x->normvalid   = PETSC_TRUE;
444:   }
445:   PetscLogEventEnd(VEC_Normalize,x,0,0,0);
446:   return(0);
447: }

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

454:    Collective on Vec

456:    Input Parameter:
457: .  x - the vector

459:    Output Parameters:
460: +  val - the maximum component
461: -  p - the location of val

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

466:    Level: intermediate

468:    Concepts: maximum^of vector
469:    Concepts: vector^maximum value

471: .seealso: VecNorm(), VecMin()
472: @*/
473: int VecMax(Vec x,int *p,PetscReal *val)
474: {

481:   PetscLogEventBegin(VEC_Max,x,0,0,0);
482:   (*x->ops->max)(x,p,val);
483:   PetscLogEventEnd(VEC_Max,x,0,0,0);
484:   return(0);
485: }

489: /*@
490:    VecMin - Determines the minimum vector component and its location.

492:    Collective on Vec

494:    Input Parameters:
495: .  x - the vector

497:    Output Parameter:
498: +  val - the minimum component
499: -  p - the location of val

501:    Level: intermediate

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

506:    Concepts: minimum^of vector
507:    Concepts: vector^minimum entry

509: .seealso: VecMax()
510: @*/
511: int VecMin(Vec x,int *p,PetscReal *val)
512: {

519:   PetscLogEventBegin(VEC_Min,x,0,0,0);
520:   (*x->ops->min)(x,p,val);
521:   PetscLogEventEnd(VEC_Min,x,0,0,0);
522:   return(0);
523: }

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

531:    Collective on Vec

533:    Input Parameters:
534: .  x, y - the vectors

536:    Output Parameter:
537: .  val - the dot product

539:    Notes for Users of Complex Numbers:
540:    For complex vectors, VecTDot() computes the indefinite form
541: $     val = (x,y) = y^T x,
542:    where y^T denotes the transpose of y.

544:    Use VecDot() for the inner product
545: $     val = (x,y) = y^H x,
546:    where y^H denotes the conjugate transpose of y.

548:    Level: intermediate

550:    Concepts: inner product^non-Hermitian
551:    Concepts: vector^inner product
552:    Concepts: non-Hermitian inner product

554: .seealso: VecDot(), VecMTDot()
555: @*/
556: int VecTDot(Vec x,Vec y,PetscScalar *val)
557: {

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

571:   PetscLogEventBegin(VEC_TDot,x,y,0,0);
572:   (*x->ops->tdot)(x,y,val);
573:   PetscLogEventEnd(VEC_TDot,x,y,0,0);
574:   return(0);
575: }

579: /*@
580:    VecScale - Scales a vector. 

582:    Collective on Vec

584:    Input Parameters:
585: +  x - the vector
586: -  alpha - the scalar

588:    Output Parameter:
589: .  x - the scaled vector

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

595:    Level: intermediate

597:    Concepts: vector^scaling
598:    Concepts: scaling^vector

600: @*/
601: int VecScale (const PetscScalar *alpha,Vec x)
602: {

609:   PetscLogEventBegin(VEC_Scale,x,0,0,0);
610:   (*x->ops->scale)(alpha,x);
611:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
612:   /*x->normvalid = PETSC_FALSE;*/
613:   if (x->normvalid) x->normcurrent = PetscAbsScalar(*alpha)*x->normcurrent;
614:   return(0);
615: }

619: /*@
620:    VecCopy - Copies a vector. 

622:    Collective on Vec

624:    Input Parameter:
625: .  x - the vector

627:    Output Parameter:
628: .  y - the copy

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

634:    Level: beginner

636: .seealso: VecDuplicate()
637: @*/
638: int VecCopy(Vec x,Vec y)
639: {

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

651:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
652:   (*x->ops->copy)(x,y);
653:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
654:   y->normvalid   = x->normvalid;
655:   y->normcurrent = x->normcurrent;
656:   return(0);
657: }

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

664:    Collective on Vec

666:    Input Parameters:
667: +  alpha - the scalar
668: -  x  - the vector

670:    Output Parameter:
671: .  x  - the vector

673:    Note:
674:    For a vector of dimension n, VecSet() computes
675: $     x[i] = alpha, for i=1,...,n,
676:    so that all vector entries then equal the identical
677:    scalar value, alpha.  Use the more general routine
678:    VecSetValues() to set different vector entries.

680:    Level: beginner

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

684:    Concepts: vector^setting to constant

686: @*/
687: int VecSet(const PetscScalar *alpha,Vec x)
688: {

695:   x->normvalid = PETSC_FALSE;

697:   PetscLogEventBegin(VEC_Set,x,0,0,0);
698:   (*x->ops->set)(alpha,x);
699:   PetscLogEventEnd(VEC_Set,x,0,0,0);
700:   return(0);
701: }

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

708:    Collective on Vec

710:    Input Parameters:
711: +  rctx - the random number context, formed by PetscRandomCreate(), or PETSC_NULL and
712:           it will create one internally.
713: -  x  - the vector

715:    Output Parameter:
716: .  x  - the vector

718:    Example of Usage:
719: .vb
720:      PetscRandomCreate(PETSC_COMM_WORLD,RANDOM_DEFAULT,&rctx);
721:      VecSetRandom(rctx,x);
722:      PetscRandomDestroy(rctx);
723: .ve

725:    Level: intermediate

727:    Concepts: vector^setting to random
728:    Concepts: random^vector

730: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
731: @*/
732: int VecSetRandom(PetscRandom rctx,Vec x)
733: {
734:   int         ierr;
735:   PetscRandom randObj = PETSC_NULL;

741:   x->normvalid = PETSC_FALSE;

743:   if (!rctx) {
744:     MPI_Comm    comm;
745:     PetscObjectGetComm((PetscObject)x,&comm);
746:     PetscRandomCreate(comm,RANDOM_DEFAULT,&randObj);
747:     rctx = randObj;
748:   }

750:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
751:   (*x->ops->setrandom)(rctx,x);
752:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);
753: 
754:   if (randObj) {
755:     PetscRandomDestroy(randObj);
756:   }
757:   return(0);
758: }

762: /*@
763:    VecAXPY - Computes y = alpha x + y. 

765:    Collective on Vec

767:    Input Parameters:
768: +  alpha - the scalar
769: -  x, y  - the vectors

771:    Output Parameter:
772: .  y - output vector

774:    Level: intermediate

776:    Concepts: vector^BLAS
777:    Concepts: BLAS

779: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
780: @*/
781: int VecAXPY(const PetscScalar *alpha,Vec x,Vec y)
782: {

793:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
794:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
795:   y->normvalid = PETSC_FALSE;

797:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
798:   (*x->ops->axpy)(alpha,x,y);
799:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
800:   return(0);
801: }

805: /*@
806:    VecAXPBY - Computes y = alpha x + beta y. 

808:    Collective on Vec

810:    Input Parameters:
811: +  alpha,beta - the scalars
812: -  x, y  - the vectors

814:    Output Parameter:
815: .  y - output vector

817:    Level: intermediate

819:    Concepts: BLAS
820:    Concepts: vector^BLAS

822: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
823: @*/
824: int VecAXPBY(const PetscScalar *alpha,const PetscScalar *beta,Vec x,Vec y)
825: {

837:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
838:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
839:   y->normvalid = PETSC_FALSE;

841:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
842:   (*x->ops->axpby)(alpha,beta,x,y);
843:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
844:   return(0);
845: }

849: /*@
850:    VecAYPX - Computes y = x + alpha y.

852:    Collective on Vec

854:    Input Parameters:
855: +  alpha - the scalar
856: -  x, y  - the vectors

858:    Output Parameter:
859: .  y - output vector

861:    Level: intermediate

863:    Concepts: vector^BLAS
864:    Concepts: BLAS

866: .seealso: VecAXPY(), VecWAXPY()
867: @*/
868: int VecAYPX(const PetscScalar *alpha,Vec x,Vec y)
869: {

880:   if (x->N != y->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
881:   if (x->n != y->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
882:   y->normvalid = PETSC_FALSE;

884:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
885:    (*x->ops->aypx)(alpha,x,y);
886:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
887:   return(0);
888: }

892: /*@
893:    VecSwap - Swaps the vectors x and y.

895:    Collective on Vec

897:    Input Parameters:
898: .  x, y  - the vectors

900:    Level: advanced

902:    Concepts: vector^swapping values

904: @*/
905: int VecSwap(Vec x,Vec y)
906: {

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

919:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
920:   (*x->ops->swap)(x,y);
921:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
922:   {
923:     PetscTruth normvalid   = x->normvalid;
924:     PetscReal  normcurrent = x->normcurrent;
925: 
926:     x->normvalid   = y->normvalid;
927:     x->normcurrent = y->normcurrent;
928:     y->normvalid   = normvalid;
929:     y->normcurrent = normcurrent;
930:   }
931:   return(0);
932: }

936: /*@
937:    VecWAXPY - Computes w = alpha x + y.

939:    Collective on Vec

941:    Input Parameters:
942: +  alpha - the scalar
943: -  x, y  - the vectors

945:    Output Parameter:
946: .  w - the result

948:    Level: intermediate

950:    Concepts: vector^BLAS
951:    Concepts: BLAS

953: .seealso: VecAXPY(), VecAYPX()
954: @*/
955: int VecWAXPY(const PetscScalar *alpha,Vec x,Vec y,Vec w)
956: {

969:   if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
970:   if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
971:   w->normvalid = PETSC_FALSE;

973:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
974:    (*x->ops->waxpy)(alpha,x,y,w);
975:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
976:   return(0);
977: }

981: /*@
982:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

984:    Collective on Vec

986:    Input Parameters:
987: .  x, y  - the vectors

989:    Output Parameter:
990: .  w - the result

992:    Level: advanced

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

996:    Concepts: vector^pointwise multiply

998: .seealso: VecPointwiseDivide()
999: @*/
1000: int VecPointwiseMult(Vec x,Vec y,Vec w)
1001: {

1013:   if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1014:   if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1015:   w->normvalid = PETSC_FALSE;

1017:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
1018:   (*x->ops->pointwisemult)(x,y,w);
1019:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
1020:   return(0);
1021: }

1025: /*@
1026:    VecPointwiseDivide - Computes the componentwise division w = x/y.

1028:    Collective on Vec

1030:    Input Parameters:
1031: .  x, y  - the vectors

1033:    Output Parameter:
1034: .  w - the result

1036:    Level: advanced

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

1040:    Concepts: vector^pointwise divide

1042: .seealso: VecPointwiseMult()
1043: @*/
1044: int VecPointwiseDivide(Vec x,Vec y,Vec w)
1045: {

1057:   if (x->N != y->N || x->N != w->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths");
1058:   if (x->n != y->n || x->n != w->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");
1059:   w->normvalid = PETSC_FALSE;

1061:   (*x->ops->pointwisedivide)(x,y,w);
1062:   return(0);
1063: }

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

1070:    Collective on Vec

1072:    Input Parameters:
1073: .  x, y  - the vectors

1075:    Output Parameter:
1076: .  max - the result

1078:    Level: advanced

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

1082: .seealso: VecPointwiseDivide(), VecPointwiseMult()
1083: @*/
1084: int VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
1085: {

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

1098:   (*x->ops->maxpointwisedivide)(x,y,max);
1099:   return(0);
1100: }

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

1107:    Collective on Vec

1109:    Input Parameters:
1110: .  v - a vector to mimic

1112:    Output Parameter:
1113: .  newv - location to put new vector

1115:    Notes:
1116:    VecDuplicate() does not copy the vector, but rather allocates storage
1117:    for the new vector.  Use VecCopy() to copy a vector.

1119:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
1120:    vectors. 

1122:    Level: beginner

1124: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
1125: @*/
1126: int VecDuplicate(Vec x,Vec *newv)
1127: {

1134:   (*x->ops->duplicate)(x,newv);
1135:   return(0);
1136: }

1140: /*@C
1141:    VecDestroy - Destroys a vector.

1143:    Collective on Vec

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

1148:    Level: beginner

1150: .seealso: VecDuplicate(), VecDestroyVecs()
1151: @*/
1152: int VecDestroy(Vec v)
1153: {

1158:   if (--v->refct > 0) return(0);
1159:   /* destroy the internal part */
1160:   if (v->ops->destroy) {
1161:     (*v->ops->destroy)(v);
1162:   }
1163:   /* destroy the external/common part */
1164:   if (v->mapping) {
1165:     ISLocalToGlobalMappingDestroy(v->mapping);
1166:   }
1167:   if (v->bmapping) {
1168:     ISLocalToGlobalMappingDestroy(v->bmapping);
1169:   }
1170:   if (v->map) {
1171:     PetscMapDestroy(v->map);
1172:   }
1173:   PetscLogObjectDestroy(v);
1174:   PetscHeaderDestroy(v);
1175:   return(0);
1176: }

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

1183:    Collective on Vec

1185:    Input Parameters:
1186: +  m - the number of vectors to obtain
1187: -  v - a vector to mimic

1189:    Output Parameter:
1190: .  V - location to put pointer to array of vectors

1192:    Notes:
1193:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
1194:    vector.

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

1201:    Level: intermediate

1203: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
1204: @*/
1205: int VecDuplicateVecs(Vec v,int m,Vec *V[])
1206: {

1213:   (*v->ops->duplicatevecs)(v, m,V);
1214:   return(0);
1215: }

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

1222:    Collective on Vec

1224:    Input Parameters:
1225: +  vv - pointer to array of vector pointers
1226: -  m - the number of vectors previously obtained

1228:    Fortran Note:
1229:    The Fortran interface is slightly different from that given below.
1230:    See the Fortran chapter of the users manual and 
1231:    petsc/src/vec/examples for details.

1233:    Level: intermediate

1235: .seealso: VecDuplicateVecs(), VecDestroyVecsF90()
1236: @*/
1237: int VecDestroyVecs(const Vec vv[],int m)
1238: {

1242:   if (!vv) SETERRQ(PETSC_ERR_ARG_BADPTR,"Null vectors");
1245:   (*(*vv)->ops->destroyvecs)(vv,m);
1246:   return(0);
1247: }

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

1254:    Input Parameters:
1255:    Not Collective

1257: +  x - vector to insert in
1258: .  ni - number of elements to add
1259: .  ix - indices where to add
1260: .  y - array of values
1261: -  iora - either INSERT_VALUES or ADD_VALUES, where
1262:    ADD_VALUES adds values to any existing entries, and
1263:    INSERT_VALUES replaces existing entries with new values

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

1268:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
1269:    options cannot be mixed without intervening calls to the assembly
1270:    routines.

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

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

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

1282:    Level: beginner

1284:    Concepts: vector^setting values

1286: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
1287:            VecSetValue(), VecSetValuesBlocked()
1288: @*/
1289: int VecSetValues(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1290: {

1298:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1299:   (*x->ops->setvalues)(x,ni,ix,y,iora);
1300:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1301:   x->normvalid = PETSC_FALSE;
1302:   return(0);
1303: }

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

1310:    Not Collective

1312:    Input Parameters:
1313: +  x - vector to insert in
1314: .  ni - number of blocks to add
1315: .  ix - indices where to add in block count, rather than element count
1316: .  y - array of values
1317: -  iora - either INSERT_VALUES or ADD_VALUES, where
1318:    ADD_VALUES adds values to any existing entries, and
1319:    INSERT_VALUES replaces existing entries with new values

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

1325:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
1326:    options cannot be mixed without intervening calls to the assembly
1327:    routines.

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

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

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

1339:    Level: intermediate

1341:    Concepts: vector^setting values blocked

1343: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
1344:            VecSetValues()
1345: @*/
1346: int VecSetValuesBlocked(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1347: {

1355:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1356:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
1357:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1358:   x->normvalid = PETSC_FALSE;
1359:   return(0);
1360: }

1364: /*@
1365:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
1366:    by the routine VecSetValuesLocal() to allow users to insert vector entries
1367:    using a local (per-processor) numbering.

1369:    Collective on Vec

1371:    Input Parameters:
1372: +  x - vector
1373: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1378:    Level: intermediate

1380:    Concepts: vector^setting values with local numbering

1382: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1383:            VecSetLocalToGlobalMappingBlocked(), VecSetValuesBlockedLocal()
1384: @*/
1385: int VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
1386: {

1392:   if (x->mapping) {
1393:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1394:   }

1396:   if (x->ops->setlocaltoglobalmapping) {
1397:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
1398:   } else {
1399:     x->mapping = mapping;
1400:     PetscObjectReference((PetscObject)mapping);
1401:   }
1402:   return(0);
1403: }

1407: /*@
1408:    VecSetLocalToGlobalMappingBlock - Sets a local numbering to global numbering used
1409:    by the routine VecSetValuesBlockedLocal() to allow users to insert vector entries
1410:    using a local (per-processor) numbering.

1412:    Collective on Vec

1414:    Input Parameters:
1415: +  x - vector
1416: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

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

1421:    Level: intermediate

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

1425: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
1426:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
1427: @*/
1428: int VecSetLocalToGlobalMappingBlock(Vec x,ISLocalToGlobalMapping mapping)
1429: {

1435:   if (x->bmapping) {
1436:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Mapping already set for vector");
1437:   }
1438:   x->bmapping = mapping;
1439:   PetscObjectReference((PetscObject)mapping);
1440:   return(0);
1441: }

1445: /*@
1446:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
1447:    using a local ordering of the nodes. 

1449:    Not Collective

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

1460:    Level: intermediate

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

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

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

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

1474:    Concepts: vector^setting values with local numbering

1476: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
1477:            VecSetValuesBlockedLocal()
1478: @*/
1479: int VecSetValuesLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1480: {
1481:   int ierr,lixp[128],*lix = lixp;


1489:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1490:   if (!x->ops->setvalueslocal) {
1491:     if (!x->mapping) {
1492:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
1493:     }
1494:     if (ni > 128) {
1495:       PetscMalloc(ni*sizeof(int),&lix);
1496:     }
1497:     ISLocalToGlobalMappingApply(x->mapping,ni,(int*)ix,lix);
1498:     (*x->ops->setvalues)(x,ni,lix,y,iora);
1499:     if (ni > 128) {
1500:       PetscFree(lix);
1501:     }
1502:   } else {
1503:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
1504:   }
1505:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1506:   x->normvalid = PETSC_FALSE;
1507:   return(0);
1508: }

1512: /*@
1513:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
1514:    using a local ordering of the nodes. 

1516:    Not Collective

1518:    Input Parameters:
1519: +  x - vector to insert in
1520: .  ni - number of blocks to add
1521: .  ix - indices where to add in block count, not element count
1522: .  y - array of values
1523: -  iora - either INSERT_VALUES or ADD_VALUES, where
1524:    ADD_VALUES adds values to any existing entries, and
1525:    INSERT_VALUES replaces existing entries with new values

1527:    Level: intermediate

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

1533:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1534:    options cannot be mixed without intervening calls to the assembly
1535:    routines.

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

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


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

1545: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
1546:            VecSetLocalToGlobalMappingBlocked()
1547: @*/
1548: int VecSetValuesBlockedLocal(Vec x,int ni,const int ix[],const PetscScalar y[],InsertMode iora)
1549: {
1550:   int ierr,lixp[128],*lix = lixp;

1557:   if (!x->bmapping) {
1558:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlocked()");
1559:   }
1560:   if (ni > 128) {
1561:     PetscMalloc(ni*sizeof(int),&lix);
1562:   }

1564:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1565:   ISLocalToGlobalMappingApply(x->bmapping,ni,(int*)ix,lix);
1566:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1567:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1568:   if (ni > 128) {
1569:     PetscFree(lix);
1570:   }
1571:   x->normvalid = PETSC_FALSE;
1572:   return(0);
1573: }

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

1581:    Collective on Vec

1583:    Input Parameter:
1584: .  vec - the vector

1586:    Level: beginner

1588:    Concepts: assembly^vectors

1590: .seealso: VecAssemblyEnd(), VecSetValues()
1591: @*/
1592: int VecAssemblyBegin(Vec vec)
1593: {
1594:   int        ierr;
1595:   PetscTruth flg;


1601:   PetscOptionsHasName(vec->prefix,"-vec_view_stash",&flg);
1602:   if (flg) {
1603:     VecStashView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1604:   }

1606:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
1607:   if (vec->ops->assemblybegin) {
1608:     (*vec->ops->assemblybegin)(vec);
1609:   }
1610:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
1611:   return(0);
1612: }

1616: /*@
1617:    VecAssemblyEnd - Completes assembling the vector.  This routine should
1618:    be called after VecAssemblyBegin().

1620:    Collective on Vec

1622:    Input Parameter:
1623: .  vec - the vector

1625:    Options Database Keys:
1626: .  -vec_view - Prints vector in ASCII format
1627: .  -vec_view_matlab - Prints vector in Matlab format
1628: .  -vec_view_draw - Activates vector viewing using drawing tools
1629: .  -display <name> - Sets display name (default is host)
1630: .  -draw_pause <sec> - Sets number of seconds to pause after display
1631: .  -vec_view_socket - Activates vector viewing using a socket
1632: -  -vec_view_ams - Activates vector viewing using the ALICE Memory Snooper (AMS)
1633:  
1634:    Level: beginner

1636: .seealso: VecAssemblyBegin(), VecSetValues()
1637: @*/
1638: int VecAssemblyEnd(Vec vec)
1639: {
1640:   int        ierr;
1641:   PetscTruth flg;

1645:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
1647:   if (vec->ops->assemblyend) {
1648:     (*vec->ops->assemblyend)(vec);
1649:   }
1650:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
1651:   PetscOptionsBegin(vec->comm,vec->prefix,"Vector Options","Vec");
1652:     PetscOptionsName("-vec_view","Print vector to stdout","VecView",&flg);
1653:     if (flg) {
1654:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1655:     }
1656:     PetscOptionsName("-vec_view_matlab","Print vector to stdout in a format Matlab can read","VecView",&flg);
1657:     if (flg) {
1658:       PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(vec->comm),PETSC_VIEWER_ASCII_MATLAB);
1659:       VecView(vec,PETSC_VIEWER_STDOUT_(vec->comm));
1660:       PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(vec->comm));
1661:     }
1662:     PetscOptionsName("-vec_view_socket","Send vector to socket (can be read from matlab)","VecView",&flg);
1663:     if (flg) {
1664:       VecView(vec,PETSC_VIEWER_SOCKET_(vec->comm));
1665:       PetscViewerFlush(PETSC_VIEWER_SOCKET_(vec->comm));
1666:     }
1667:     PetscOptionsName("-vec_view_binary","Save vector to file in binary format","VecView",&flg);
1668:     if (flg) {
1669:       VecView(vec,PETSC_VIEWER_BINARY_(vec->comm));
1670:       PetscViewerFlush(PETSC_VIEWER_BINARY_(vec->comm));
1671:     }
1672: #if defined(PETSC_HAVE_AMS)
1673:     PetscOptionsName("-vec_view_ams","View vector using AMS","VecView",&flg);
1674:     if (flg) {
1675:       VecView(vec,PETSC_VIEWER_AMS_(vec->comm));
1676:     }
1677: #endif
1678:   PetscOptionsEnd();
1679:   /* These invoke PetscDrawGetDraw which invokes PetscOptionsBegin/End, */
1680:   /* hence they should not be inside the above PetscOptionsBegin/End block. */
1681:   PetscOptionsHasName(vec->prefix,"-vec_view_draw",&flg);
1682:   if (flg) {
1683:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1684:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1685:   }
1686:   PetscOptionsHasName(vec->prefix,"-vec_view_draw_lg",&flg);
1687:   if (flg) {
1688:     PetscViewerSetFormat(PETSC_VIEWER_DRAW_(vec->comm),PETSC_VIEWER_DRAW_LG);
1689:     VecView(vec,PETSC_VIEWER_DRAW_(vec->comm));
1690:     PetscViewerFlush(PETSC_VIEWER_DRAW_(vec->comm));
1691:   }
1692:   vec->normvalid = PETSC_FALSE;
1693:   return(0);
1694: }


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

1703:    Collective on Vec

1705:    Input Parameters:
1706: +  nv - number of vectors
1707: .  x - one vector
1708: -  y - array of vectors.  Note that vectors are pointers

1710:    Output Parameter:
1711: .  val - array of the dot products

1713:    Notes for Users of Complex Numbers:
1714:    For complex vectors, VecMTDot() computes the indefinite form
1715: $      val = (x,y) = y^T x,
1716:    where y^T denotes the transpose of y.

1718:    Use VecMDot() for the inner product
1719: $      val = (x,y) = y^H x,
1720:    where y^H denotes the conjugate transpose of y.

1722:    Level: intermediate

1724:    Concepts: inner product^multiple
1725:    Concepts: vector^multiple inner products

1727: .seealso: VecMDot(), VecTDot()
1728: @*/
1729: int VecMTDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1730: {

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

1744:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1745:   (*x->ops->mtdot)(nv,x,y,val);
1746:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1747:   return(0);
1748: }

1752: /*@C
1753:    VecMDot - Computes vector multiple dot products. 

1755:    Collective on Vec

1757:    Input Parameters:
1758: +  nv - number of vectors
1759: .  x - one vector
1760: -  y - array of vectors. 

1762:    Output Parameter:
1763: .  val - array of the dot products

1765:    Notes for Users of Complex Numbers:
1766:    For complex vectors, VecMDot() computes 
1767: $     val = (x,y) = y^H x,
1768:    where y^H denotes the conjugate transpose of y.

1770:    Use VecMTDot() for the indefinite form
1771: $     val = (x,y) = y^T x,
1772:    where y^T denotes the transpose of y.

1774:    Level: intermediate

1776:    Concepts: inner product^multiple
1777:    Concepts: vector^multiple inner products

1779: .seealso: VecMTDot(), VecDot()
1780: @*/
1781: int VecMDot(int nv,Vec x,const Vec y[],PetscScalar *val)
1782: {

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

1796:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,x->comm);
1797:   (*x->ops->mdot)(nv,x,y,val);
1798:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,x->comm);
1799:   return(0);
1800: }

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

1807:    Collective on Vec

1809:    Input Parameters:
1810: +  nv - number of scalars and x-vectors
1811: .  alpha - array of scalars
1812: .  y - one vector
1813: -  x - array of vectors

1815:    Level: intermediate

1817:    Concepts: BLAS

1819: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1820: @*/
1821: int  VecMAXPY(int nv,const PetscScalar *alpha,Vec y,Vec *x)
1822: {

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

1836:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1837:   (*y->ops->maxpy)(nv,alpha,y,x);
1838:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1839:   y->normvalid = PETSC_FALSE;
1840:   return(0);
1841: }

1845: /*@C
1846:    VecGetArray - Returns a pointer to a contiguous array that contains this 
1847:    processor's portion of the vector data. For the standard PETSc
1848:    vectors, VecGetArray() returns a pointer to the local data array and
1849:    does not use any copies. If the underlying vector data is not stored
1850:    in a contiquous array this routine will copy the data to a contiquous
1851:    array and return a pointer to that. You MUST call VecRestoreArray() 
1852:    when you no longer need access to the array.

1854:    Not Collective

1856:    Input Parameter:
1857: .  x - the vector

1859:    Output Parameter:
1860: .  a - location to put pointer to the array

1862:    Fortran Note:
1863:    This routine is used differently from Fortran 77
1864: $    Vec         x
1865: $    PetscScalar x_array(1)
1866: $    PetscOffset i_x
1867: $    int         ierr
1868: $       call VecGetArray(x,x_array,i_x,ierr)
1869: $
1870: $   Access first local entry in vector with
1871: $      value = x_array(i_x + 1)
1872: $
1873: $      ...... other code
1874: $       call VecRestoreArray(x,x_array,i_x,ierr)
1875:    For Fortran 90 see VecGetArrayF90()

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

1880:    Level: beginner

1882:    Concepts: vector^accessing local values

1884: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1885: @*/
1886: int VecGetArray(Vec x,PetscScalar *a[])
1887: {

1894:   (*x->ops->getarray)(x,a);
1895:   return(0);
1896: }


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

1906:    Not Collective

1908:    Input Parameter:
1909: +  x - the vectors
1910: -  n - the number of vectors

1912:    Output Parameter:
1913: .  a - location to put pointer to the array

1915:    Fortran Note:
1916:    This routine is not supported in Fortran.

1918:    Level: intermediate

1920: .seealso: VecGetArray(), VecRestoreArrays()
1921: @*/
1922: int VecGetArrays(const Vec x[],int n,PetscScalar **a[])
1923: {
1924:   int         i,ierr;
1925:   PetscScalar **q;

1930:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %d",n);
1931:   PetscMalloc(n*sizeof(PetscScalar*),&q);
1932:   for (i=0; i<n; ++i) {
1933:     VecGetArray(x[i],&q[i]);
1934:   }
1935:   *a = q;
1936:   return(0);
1937: }

1941: /*@C
1942:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1943:    has been called.

1945:    Not Collective

1947:    Input Parameters:
1948: +  x - the vector
1949: .  n - the number of vectors
1950: -  a - location of pointer to arrays obtained from VecGetArrays()

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

1958:    Fortran Note:
1959:    This routine is not supported in Fortran.

1961:    Level: intermediate

1963: .seealso: VecGetArrays(), VecRestoreArray()
1964: @*/
1965: int VecRestoreArrays(const Vec x[],int n,PetscScalar **a[])
1966: {
1967:   int         i,ierr;
1968:   PetscScalar **q = *a;


1974:   for(i=0;i<n;++i) {
1975:     VecRestoreArray(x[i],&q[i]);
1976:     x[i]->normvalid = PETSC_FALSE;
1977:  }
1978:   PetscFree(q);
1979:   return(0);
1980: }

1984: /*@C
1985:    VecRestoreArray - Restores a vector after VecGetArray() has been called.

1987:    Not Collective

1989:    Input Parameters:
1990: +  x - the vector
1991: -  a - location of pointer to array obtained from VecGetArray()

1993:    Level: beginner

1995:    Notes:
1996:    For regular PETSc vectors this routine does not involve any copies. For
1997:    any special vectors that do not store local vector data in a contiguous
1998:    array, this routine will copy the data back into the underlying 
1999:    vector data structure from the array obtained with VecGetArray().

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

2005:    Fortran Note:
2006:    This routine is used differently from Fortran 77
2007: $    Vec         x
2008: $    PetscScalar x_array(1)
2009: $    PetscOffset i_x
2010: $    int         ierr
2011: $       call VecGetArray(x,x_array,i_x,ierr)
2012: $
2013: $   Access first local entry in vector with
2014: $      value = x_array(i_x + 1)
2015: $
2016: $      ...... other code
2017: $       call VecRestoreArray(x,x_array,i_x,ierr)

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

2023: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
2024: @*/
2025: int VecRestoreArray(Vec x,PetscScalar *a[])
2026: {

2033: #if defined(PETSC_USE_BOPT_g)
2034:   CHKMEMQ;
2035: #endif
2036:   if (x->ops->restorearray) {
2037:     (*x->ops->restorearray)(x,a);
2038:   }
2039:   x->normvalid = PETSC_FALSE;
2040:   return(0);
2041: }

2043: #undef  __FUNCT__
2045: /*@
2046:   VecViewFromOptions - This function visualizes the vector based upon user options.

2048:   Collective on Vec

2050:   Input Parameters:
2051: . vec   - The vector
2052: . title - The title

2054:   Level: intermediate

2056: .keywords: Vec, view, options, database
2057: .seealso: VecSetFromOptions(), VecView()
2058: @*/
2059: int VecViewFromOptions(Vec vec, char *title)
2060: {
2061:   PetscViewer viewer;
2062:   PetscDraw   draw;
2063:   PetscTruth  opt;
2064:   char       *titleStr;
2065:   char        typeName[1024];
2066:   char        fileName[PETSC_MAX_PATH_LEN];
2067:   int         len;
2068:   int         ierr;

2071:   PetscOptionsHasName(vec->prefix, "-vec_view", &opt);
2072:   if (opt == PETSC_TRUE) {
2073:     PetscOptionsGetString(vec->prefix, "-vec_view", typeName, 1024, &opt);
2074:     PetscStrlen(typeName, &len);
2075:     if (len > 0) {
2076:       PetscViewerCreate(vec->comm, &viewer);
2077:       PetscViewerSetType(viewer, typeName);
2078:       PetscOptionsGetString(vec->prefix, "-vec_view_file", fileName, 1024, &opt);
2079:       if (opt == PETSC_TRUE) {
2080:         PetscViewerSetFilename(viewer, fileName);
2081:       } else {
2082:         PetscViewerSetFilename(viewer, vec->name);
2083:       }
2084:       VecView(vec, viewer);
2085:       PetscViewerFlush(viewer);
2086:       PetscViewerDestroy(viewer);
2087:     } else {
2088:       VecView(vec, PETSC_VIEWER_STDOUT_(vec->comm));
2089:     }
2090:   }
2091:   PetscOptionsHasName(vec->prefix, "-vec_view_draw", &opt);
2092:   if (opt == PETSC_TRUE) {
2093:     PetscViewerDrawOpen(vec->comm, 0, 0, 0, 0, 300, 300, &viewer);
2094:     PetscViewerDrawGetDraw(viewer, 0, &draw);
2095:     if (title != PETSC_NULL) {
2096:       titleStr = title;
2097:     } else {
2098:       PetscObjectName((PetscObject) vec);                                                          CHKERRQ(ierr) ;
2099:       titleStr = vec->name;
2100:     }
2101:     PetscDrawSetTitle(draw, titleStr);
2102:     VecView(vec, viewer);
2103:     PetscViewerFlush(viewer);
2104:     PetscDrawPause(draw);
2105:     PetscViewerDestroy(viewer);
2106:   }
2107:   return(0);
2108: }

2112: /*@C
2113:    VecView - Views a vector object. 

2115:    Collective on Vec

2117:    Input Parameters:
2118: +  v - the vector
2119: -  viewer - an optional visualization context

2121:    Notes:
2122:    The available visualization contexts include
2123: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
2124: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
2125:          output where only the first processor opens
2126:          the file.  All other processors send their 
2127:          data to the first processor to print. 

2129:    You can change the format the vector is printed using the 
2130:    option PetscViewerSetFormat().

2132:    The user can open alternative visualization contexts with
2133: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
2134: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
2135:          specified file; corresponding input uses VecLoad()
2136: .    PetscViewerDrawOpen() - Outputs vector to an X window display
2137: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

2139:    The user can call PetscViewerSetFormat() to specify the output
2140:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
2141:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
2142: +    PETSC_VIEWER_ASCII_DEFAULT - default, prints vector contents
2143: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in Matlab format
2144: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
2145: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a 
2146:          format common among all vector types

2148:    Level: beginner

2150:    Concepts: vector^printing
2151:    Concepts: vector^saving to disk

2153: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
2154:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
2155:           PetscRealView(), PetscScalarView(), PetscIntView()
2156: @*/
2157: int VecView(Vec vec,PetscViewer viewer)
2158: {
2159:   int               ierr;
2160:   PetscViewerFormat format;

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

2170:   /*
2171:      Check if default viewer has been overridden, but user request it anyways
2172:   */
2173:   PetscViewerGetFormat(viewer,&format);
2174:   if (vec->ops->viewnative && format == PETSC_VIEWER_NATIVE) {
2175:     PetscViewerPopFormat(viewer);
2176:     (*vec->ops->viewnative)(vec,viewer);
2177:     PetscViewerPushFormat(viewer,PETSC_VIEWER_NATIVE);
2178:   } else {
2179:     (*vec->ops->view)(vec,viewer);
2180:   }
2181:   return(0);
2182: }

2186: /*@
2187:    VecGetSize - Returns the global number of elements of the vector.

2189:    Not Collective

2191:    Input Parameter:
2192: .  x - the vector

2194:    Output Parameters:
2195: .  size - the global length of the vector

2197:    Level: beginner

2199:    Concepts: vector^local size

2201: .seealso: VecGetLocalSize()
2202: @*/
2203: int VecGetSize(Vec x,int *size)
2204: {

2211:   (*x->ops->getsize)(x,size);
2212:   return(0);
2213: }

2217: /*@
2218:    VecGetLocalSize - Returns the number of elements of the vector stored 
2219:    in local memory. This routine may be implementation dependent, so use 
2220:    with care.

2222:    Not Collective

2224:    Input Parameter:
2225: .  x - the vector

2227:    Output Parameter:
2228: .  size - the length of the local piece of the vector

2230:    Level: beginner

2232:    Concepts: vector^size

2234: .seealso: VecGetSize()
2235: @*/
2236: int VecGetLocalSize(Vec x,int *size)
2237: {

2244:   (*x->ops->getlocalsize)(x,size);
2245:   return(0);
2246: }

2250: /*@C
2251:    VecGetOwnershipRange - Returns the range of indices owned by 
2252:    this processor, assuming that the vectors are laid out with the
2253:    first n1 elements on the first processor, next n2 elements on the
2254:    second, etc.  For certain parallel layouts this range may not be 
2255:    well defined. 

2257:    Not Collective

2259:    Input Parameter:
2260: .  x - the vector

2262:    Output Parameters:
2263: +  low - the first local element, pass in PETSC_NULL if not interested
2264: -  high - one more than the last local element, pass in PETSC_NULL if not interested

2266:    Note:
2267:    The high argument is one more than the last element stored locally.

2269:    Fortran: PETSC_NULL_INTEGER should be used instead of PETSC_NULL

2271:    Level: beginner

2273:    Concepts: ownership^of vectors
2274:    Concepts: vector^ownership of elements

2276: @*/
2277: int VecGetOwnershipRange(Vec x,int *low,int *high)
2278: {
2279:   int      ierr;

2286:   PetscMapGetLocalRange(x->map,low,high);
2287:   return(0);
2288: }

2292: /*@C
2293:    VecGetPetscMap - Returns the map associated with the vector

2295:    Not Collective

2297:    Input Parameter:
2298: .  x - the vector

2300:    Output Parameters:
2301: .  map - the map

2303:    Level: developer

2305: @*/
2306: int VecGetPetscMap(Vec x,PetscMap *map)
2307: {
2311:   *map = x->map;
2312:   return(0);
2313: }

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

2320:    Collective on Vec

2322:    Input Parameter:
2323: +  x - the vector
2324: -  op - the option

2326:    Supported Options:
2327: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore 
2328:       entries destined to be stored on a seperate processor. This can be used
2329:       to eliminate the global reduction in the VecAssemblyXXXX() if you know 
2330:       that you have only used VecSetValues() to set local elements
2331: -   VEC_TREAT_OFF_PROC_ENTRIES restores the treatment of off processor entries.

2333:    Level: intermediate

2335: @*/
2336: int VecSetOption(Vec x,VecOption op)
2337: {

2343:   if (x->ops->setoption) {
2344:     (*x->ops->setoption)(x,op);
2345:   }
2346:   return(0);
2347: }

2351: /* Default routines for obtaining and releasing; */
2352: /* may be used by any implementation */
2353: int VecDuplicateVecs_Default(Vec w,int m,Vec *V[])
2354: {
2355:   int  i,ierr;

2360:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2361:   PetscMalloc(m*sizeof(Vec*),V);
2362:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
2363:   return(0);
2364: }

2368: int VecDestroyVecs_Default(const Vec v[], int m)
2369: {
2370:   int i,ierr;

2374:   if (m <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %d",m);
2375:   for (i=0; i<m; i++) {VecDestroy(v[i]);}
2376:   PetscFree((Vec*)v);
2377:   return(0);
2378: }

2382: /*@
2383:    VecPlaceArray - Allows one to replace the array in a vector with an
2384:    array provided by the user. This is useful to avoid copying an array
2385:    into a vector.

2387:    Not Collective

2389:    Input Parameters:
2390: +  vec - the vector
2391: -  array - the array

2393:    Notes:
2394:    You can return to the original array with a call to VecResetArray()

2396:    Level: developer

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

2400: @*/
2401: int VecPlaceArray(Vec vec,const PetscScalar array[])
2402: {

2408:   if (vec->ops->placearray) {
2409:     (*vec->ops->placearray)(vec,array);
2410:     vec->normvalid = PETSC_FALSE;
2411:   } else {
2412:     SETERRQ(1,"Cannot place array in this type of vector");
2413:   }
2414:   return(0);
2415: }

2419: /*@
2420:    VecResetArray - Resets a vector to use its default memory. Call this 
2421:    after the use of VecPlaceArray().

2423:    Not Collective

2425:    Input Parameters:
2426: .  vec - the vector

2428:    Level: developer

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

2432: @*/
2433: int VecResetArray(Vec vec)
2434: {

2440:   if (vec->ops->resetarray) {
2441:     (*vec->ops->resetarray)(vec);
2442:     vec->normvalid = PETSC_FALSE;
2443:   } else {
2444:     SETERRQ(1,"Cannot reset array in this type of vector");
2445:   }
2446:   return(0);
2447: }

2451: /*@C
2452:    VecReplaceArray - Allows one to replace the array in a vector with an
2453:    array provided by the user. This is useful to avoid copying an array
2454:    into a vector.

2456:    Not Collective

2458:    Input Parameters:
2459: +  vec - the vector
2460: -  array - the array

2462:    Notes:
2463:    This permanently replaces the array and frees the memory associated
2464:    with the old array.

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

2469:    Not supported from Fortran

2471:    Level: developer

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

2475: @*/
2476: int VecReplaceArray(Vec vec,const PetscScalar array[])
2477: {

2483:   if (vec->ops->replacearray) {
2484:     (*vec->ops->replacearray)(vec,array);
2485:     vec->normvalid = PETSC_FALSE;
2486:  } else {
2487:     SETERRQ(1,"Cannot replace array in this type of vector");
2488:   }
2489:   return(0);
2490: }

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

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

2499:     Collective on Vec

2501:     Input Parameters:
2502: +   x - a vector to mimic
2503: -   n - the number of vectors to obtain

2505:     Output Parameters:
2506: +   y - Fortran90 pointer to the array of vectors
2507: -   ierr - error code

2509:     Example of Usage: 
2510: .vb
2511:     Vec x
2512:     Vec, pointer :: y(:)
2513:     ....
2514:     call VecDuplicateVecsF90(x,2,y,ierr)
2515:     call VecSet(alpha,y(2),ierr)
2516:     call VecSet(alpha,y(2),ierr)
2517:     ....
2518:     call VecDestroyVecsF90(y,2,ierr)
2519: .ve

2521:     Notes:
2522:     Not yet supported for all F90 compilers

2524:     Use VecDestroyVecsF90() to free the space.

2526:     Level: beginner

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

2530: M*/

2532: /*MC
2533:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
2534:     VecGetArrayF90().

2536:     Synopsis:
2537:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2539:     Not collective

2541:     Input Parameters:
2542: +   x - vector
2543: -   xx_v - the Fortran90 pointer to the array

2545:     Output Parameter:
2546: .   ierr - error code

2548:     Example of Usage: 
2549: .vb
2550:     PetscScalar, pointer :: xx_v(:)
2551:     ....
2552:     call VecGetArrayF90(x,xx_v,ierr)
2553:     a = xx_v(3)
2554:     call VecRestoreArrayF90(x,xx_v,ierr)
2555: .ve
2556:    
2557:     Notes:
2558:     Not yet supported for all F90 compilers

2560:     Level: beginner

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

2564: M*/

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

2569:     Synopsis:
2570:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

2572:     Input Parameters:
2573: +   x - pointer to array of vector pointers
2574: -   n - the number of vectors previously obtained

2576:     Output Parameter:
2577: .   ierr - error code

2579:     Notes:
2580:     Not yet supported for all F90 compilers

2582:     Level: beginner

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

2586: M*/

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

2594:     Synopsis:
2595:     VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

2597:     Not Collective 

2599:     Input Parameter:
2600: .   x - vector

2602:     Output Parameters:
2603: +   xx_v - the Fortran90 pointer to the array
2604: -   ierr - error code

2606:     Example of Usage: 
2607: .vb
2608:     PetscScalar, pointer :: xx_v(:)
2609:     ....
2610:     call VecGetArrayF90(x,xx_v,ierr)
2611:     a = xx_v(3)
2612:     call VecRestoreArrayF90(x,xx_v,ierr)
2613: .ve

2615:     Notes:
2616:     Not yet supported for all F90 compilers

2618:     Level: beginner

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

2622: M*/

2626: /*@C 
2627:   VecLoadIntoVector - Loads a vector that has been stored in binary format
2628:   with VecView().

2630:   Collective on PetscViewer 

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

2636:   Level: intermediate

2638:   Notes:
2639:   The input file must contain the full global vector, as
2640:   written by the routine VecView().

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

2644:   Notes for advanced users:
2645:   Most users should not need to know the details of the binary storage
2646:   format, since VecLoad() and VecView() completely hide these details.
2647:   But for anyone who's interested, the standard binary matrix storage
2648:   format is
2649: .vb
2650:      int    VEC_FILE_COOKIE
2651:      int    number of rows
2652:      PetscScalar *values of all nonzeros
2653: .ve

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

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

2668:    Concepts: vector^loading from file

2670: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad() 
2671: @*/
2672: int VecLoadIntoVector(PetscViewer viewer,Vec vec)
2673: {

2680:   if (!vec->ops->loadintovector) {
2681:     SETERRQ(1,"Vector does not support load");
2682:   }
2683:   (*vec->ops->loadintovector)(viewer,vec);
2684:   vec->normvalid = PETSC_FALSE;
2685:   return(0);
2686: }

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

2693:    Collective on Vec

2695:    Input Parameter:
2696: .  v - the vector 

2698:    Output Parameter:
2699: .  v - the vector reciprocal

2701:    Level: intermediate

2703:    Concepts: vector^reciprocal

2705: @*/
2706: int VecReciprocal(Vec vec)
2707: {
2708:   int    ierr;

2713:   if (!vec->ops->reciprocal) {
2714:     SETERRQ(1,"Vector does not support reciprocal operation");
2715:   }
2716:   (*vec->ops->reciprocal)(vec);
2717:   vec->normvalid = PETSC_FALSE;
2718:   return(0);
2719: }

2723: int VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
2724: {
2727:   /* save the native version of the viewer */
2728:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
2729:     vec->ops->viewnative = vec->ops->view;
2730:   }
2731:   (((void(**)(void))vec->ops)[(int)op]) = f;
2732:   return(0);
2733: }

2737: /*@
2738:    VecSetStashInitialSize - sets the sizes of the vec-stash, that is
2739:    used during the assembly process to store values that belong to 
2740:    other processors.

2742:    Collective on Vec

2744:    Input Parameters:
2745: +  vec   - the vector
2746: .  size  - the initial size of the stash.
2747: -  bsize - the initial size of the block-stash(if used).

2749:    Options Database Keys:
2750: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
2751: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

2753:    Level: intermediate

2755:    Notes: 
2756:      The block-stash is used for values set with VecSetValuesBlocked() while
2757:      the stash is used for values set with VecSetValues()

2759:      Run with the option -log_info and look for output of the form
2760:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
2761:      to determine the appropriate value, MM, to use for size and 
2762:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
2763:      to determine the value, BMM to use for bsize

2765:    Concepts: vector^stash
2766:    Concepts: stash^vector

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

2770: @*/
2771: int VecSetStashInitialSize(Vec vec,int size,int bsize)
2772: {

2777:   VecStashSetInitialSize_Private(&vec->stash,size);
2778:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
2779:   return(0);
2780: }

2784: /*@
2785:    VecStashView - Prints the entries in the vector stash and block stash.

2787:    Collective on Vec

2789:    Input Parameters:
2790: +  vec   - the vector
2791: -  viewer - the viewer

2793:    Level: advanced

2795:    Concepts: vector^stash
2796:    Concepts: stash^vector

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

2800: @*/
2801: int VecStashView(Vec v,PetscViewer viewer)
2802: {
2803:   int          ierr,rank,i,j;
2804:   PetscTruth   match;
2805:   VecStash     *s;
2806:   PetscScalar  val;


2813:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&match);
2814:   if (!match) SETERRQ1(1,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
2815:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
2816:   MPI_Comm_rank(v->comm,&rank);
2817:   s = &v->bstash;

2819:   /* print block stash */
2820:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %d block size %d\n",rank,s->n,s->bs);
2821:   for (i=0; i<s->n; i++) {
2822:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d ",rank,s->idx[i]);
2823:     for (j=0; j<s->bs; j++) {
2824:       val = s->array[i*s->bs+j];
2825: #if defined(PETSC_USE_COMPLEX)
2826:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
2827: #else
2828:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
2829: #endif
2830:     }
2831:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
2832:   }
2833:   PetscViewerFlush(viewer);

2835:   s = &v->stash;

2837:   /* print basic stash */
2838:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %d\n",rank,s->n);
2839:   for (i=0; i<s->n; i++) {
2840:     val = s->array[i];
2841: #if defined(PETSC_USE_COMPLEX)
2842:       PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
2843: #else
2844:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %d %18.16e\n",rank,s->idx[i],val);
2845: #endif
2846:   }
2847:   PetscViewerFlush(viewer);

2849:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
2850:   return(0);
2851: }

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

2860:    Not Collective

2862:    Input Parameter:
2863: +  x - the vector
2864: .  m - first dimension of two dimensional array
2865: .  n - second dimension of two dimensional array
2866: .  mstart - first index you will use in first coordinate direction (often 0)
2867: -  nstart - first index in the second coordinate direction (often 0)

2869:    Output Parameter:
2870: .  a - location to put pointer to the array

2872:    Level: beginner

2874:   Notes:
2875:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
2876:    obtained from the corner indices obtained from DAGetGhostCorners() while for
2877:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
2878:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray2d().
2879:    
2880:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

2884: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2885:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2886:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2887: @*/
2888: int VecGetArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
2889: {
2890:   int         i,ierr,N;
2891:   PetscScalar *aa;

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

2901:   PetscMalloc(m*sizeof(PetscScalar*),a);
2902:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
2903:   *a -= mstart;
2904:   return(0);
2905: }

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

2912:    Not Collective

2914:    Input Parameters:
2915: +  x - the vector
2916: .  m - first dimension of two dimensional array
2917: .  n - second dimension of the two dimensional array
2918: .  mstart - first index you will use in first coordinate direction (often 0)
2919: .  nstart - first index in the second coordinate direction (often 0)
2920: -  a - location of pointer to array obtained from VecGetArray2d()

2922:    Level: beginner

2924:    Notes:
2925:    For regular PETSc vectors this routine does not involve any copies. For
2926:    any special vectors that do not store local vector data in a contiguous
2927:    array, this routine will copy the data back into the underlying 
2928:    vector data structure from the array obtained with VecGetArray().

2930:    This routine actually zeros out the a pointer. 

2932: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2933:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
2934:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2935: @*/
2936: int VecRestoreArray2d(Vec x,int m,int n,int mstart,int nstart,PetscScalar **a[])
2937: {

2943:   PetscFree(*a + mstart);
2944:   VecRestoreArray(x,PETSC_NULL);
2945:   return(0);
2946: }

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

2955:    Not Collective

2957:    Input Parameter:
2958: +  x - the vector
2959: .  m - first dimension of two dimensional array
2960: -  mstart - first index you will use in first coordinate direction (often 0)

2962:    Output Parameter:
2963: .  a - location to put pointer to the array

2965:    Level: beginner

2967:   Notes:
2968:    For a vector obtained from DACreateLocalVector() mstart are likely
2969:    obtained from the corner indices obtained from DAGetGhostCorners() while for
2970:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
2971:    
2972:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

2974: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
2975:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
2976:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
2977: @*/
2978: int VecGetArray1d(Vec x,int m,int mstart,PetscScalar *a[])
2979: {
2980:   int ierr,N;

2986:   VecGetLocalSize(x,&N);
2987:   if (m != N) SETERRQ2(1,"Local array size %d does not match 1d array dimensions %d",N,m);
2988:   VecGetArray(x,a);
2989:   *a  -= mstart;
2990:   return(0);
2991: }

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

2998:    Not Collective

3000:    Input Parameters:
3001: +  x - the vector
3002: .  m - first dimension of two dimensional array
3003: .  mstart - first index you will use in first coordinate direction (often 0)
3004: -  a - location of pointer to array obtained from VecGetArray21()

3006:    Level: beginner

3008:    Notes:
3009:    For regular PETSc vectors this routine does not involve any copies. For
3010:    any special vectors that do not store local vector data in a contiguous
3011:    array, this routine will copy the data back into the underlying 
3012:    vector data structure from the array obtained with VecGetArray1d().

3014:    This routine actually zeros out the a pointer. 

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

3018: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3019:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3020:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
3021: @*/
3022: int VecRestoreArray1d(Vec x,int m,int mstart,PetscScalar *a[])
3023: {

3029:   VecRestoreArray(x,PETSC_NULL);
3030:   return(0);
3031: }

3035: /*@C
3036:    VecConjugate - Conjugates a vector.

3038:    Collective on Vec

3040:    Input Parameters:
3041: .  x - the vector

3043:    Level: intermediate

3045:    Concepts: vector^conjugate

3047: @*/
3048: int VecConjugate(Vec x)
3049: {
3050: #ifdef PETSC_USE_COMPLEX

3056:   (*x->ops->conjugate)(x);
3057:   x->normvalid = PETSC_FALSE;
3058:   return(0);
3059: #else
3060:   return(0);
3061: #endif
3062: }

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

3071:    Not Collective

3073:    Input Parameter:
3074: +  x - the vector
3075: .  m - first dimension of three dimensional array
3076: .  n - second dimension of three dimensional array
3077: .  p - third dimension of three dimensional array
3078: .  mstart - first index you will use in first coordinate direction (often 0)
3079: .  nstart - first index in the second coordinate direction (often 0)
3080: -  pstart - first index in the third coordinate direction (often 0)

3082:    Output Parameter:
3083: .  a - location to put pointer to the array

3085:    Level: beginner

3087:   Notes:
3088:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
3089:    obtained from the corner indices obtained from DAGetGhostCorners() while for
3090:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
3091:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
3092:    
3093:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

3097: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
3098:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
3099:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
3100: @*/
3101: int VecGetArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3102: {
3103:   int         i,ierr,N,j;
3104:   PetscScalar *aa,**b;

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

3114:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
3115:   b    = (PetscScalar **)((*a) + m);
3116:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
3117:   for (i=0; i<m; i++) {
3118:     for (j=0; j<n; j++) {
3119:       b[i*n+j] = aa + i*n*p + j*p - pstart;
3120:     }
3121:   }
3122:   *a -= mstart;
3123:   return(0);
3124: }

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

3131:    Not Collective

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

3143:    Level: beginner

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

3151:    This routine actually zeros out the a pointer. 

3153: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
3154:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
3155:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
3156: @*/
3157: int VecRestoreArray3d(Vec x,int m,int n,int p,int mstart,int nstart,int pstart,PetscScalar ***a[])
3158: {

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