Actual source code: rvector.c

  1: #define PETSCVEC_DLL

  3: /*
  4:      Provides the interface functions for vector operations that have PetscScalar/PetscReal in the signature
  5:    These are the vector functions the user calls.
  6: */
 7:  #include private/vecimpl.h

 10:   if ((x)->map->N != (y)->map->N) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector global lengths"); \
 11:   if ((x)->map->n != (y)->map->n) SETERRQ(PETSC_ERR_ARG_INCOMP,"Incompatible vector local lengths");


 16: /*@
 17:    VecMaxPointwiseDivide - Computes the maximum of the componentwise division max = max_i abs(x_i/y_i).

 19:    Collective on Vec

 21:    Input Parameters:
 22: .  x, y  - the vectors

 24:    Output Parameter:
 25: .  max - the result

 27:    Level: advanced

 29:    Notes: any subset of the x and may be the same vector.
 30:           if a particular y_i is zero, it is treated as 1 in the above formula

 32: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs()
 33: @*/
 34: PetscErrorCode  VecMaxPointwiseDivide(Vec x,Vec y,PetscReal *max)
 35: {


 47:   (*x->ops->maxpointwisedivide)(x,y,max);
 48:   return(0);
 49: }

 53: /*@
 54:    VecDot - Computes the vector dot product.

 56:    Collective on Vec

 58:    Input Parameters:
 59: .  x, y - the vectors

 61:    Output Parameter:
 62: .  val - the dot product

 64:    Performance Issues:
 65: +    per-processor memory bandwidth
 66: .    interprocessor latency
 67: -    work load inbalance that causes certain processes to arrive much earlier than
 68:      others

 70:    Notes for Users of Complex Numbers:
 71:    For complex vectors, VecDot() computes 
 72: $     val = (x,y) = y^H x,
 73:    where y^H denotes the conjugate transpose of y.

 75:    Use VecTDot() for the indefinite form
 76: $     val = (x,y) = y^T x,
 77:    where y^T denotes the transpose of y.

 79:    Level: intermediate

 81:    Concepts: inner product
 82:    Concepts: vector^inner product

 84: .seealso: VecMDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd()
 85: @*/
 86: PetscErrorCode  VecDot(Vec x,Vec y,PetscScalar *val)
 87: {


 99:   PetscLogEventBarrierBegin(VEC_DotBarrier,x,y,0,0,((PetscObject)x)->comm);
100:   (*x->ops->dot)(x,y,val);
101:   PetscLogEventBarrierEnd(VEC_DotBarrier,x,y,0,0,((PetscObject)x)->comm);
102:   return(0);
103: }

107: /*@
108:    VecNorm  - Computes the vector norm.

110:    Collective on Vec

112:    Input Parameters:
113: +  x - the vector
114: -  type - one of NORM_1, NORM_2, NORM_INFINITY.  Also available
115:           NORM_1_AND_2, which computes both norms and stores them
116:           in a two element array.

118:    Output Parameter:
119: .  val - the norm 

121:    Notes:
122: $     NORM_1 denotes sum_i |x_i|
123: $     NORM_2 denotes sqrt(sum_i (x_i)^2)
124: $     NORM_INFINITY denotes max_i |x_i|

126:    Level: intermediate

128:    Performance Issues:
129: +    per-processor memory bandwidth
130: .    interprocessor latency
131: -    work load inbalance that causes certain processes to arrive much earlier than
132:      others

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

139:    Concepts: norm
140:    Concepts: vector^norm

142: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNormAvailable(),
143:           VecNormBegin(), VecNormEnd()

145: @*/
146: PetscErrorCode  VecNorm(Vec x,NormType type,PetscReal *val)
147: {
148:   PetscTruth     flg;


156:   /*
157:    * Cached data?
158:    */
159:   if (type!=NORM_1_AND_2) {
160:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,flg);
161:     if (flg) return(0);
162:   }

164:   PetscLogEventBarrierBegin(VEC_NormBarrier,x,0,0,0,((PetscObject)x)->comm);
165:   (*x->ops->norm)(x,type,val);
166:   PetscLogEventBarrierEnd(VEC_NormBarrier,x,0,0,0,((PetscObject)x)->comm);

168:   if (type!=NORM_1_AND_2) {
169:     PetscObjectComposedDataSetReal((PetscObject)x,NormIds[type],*val);
170:   }
171:   return(0);
172: }

176: /*@
177:    VecNormAvailable  - Returns the vector norm if it is already known.

179:    Collective on Vec

181:    Input Parameters:
182: +  x - the vector
183: -  type - one of NORM_1, NORM_2, NORM_INFINITY.  Also available
184:           NORM_1_AND_2, which computes both norms and stores them
185:           in a two element array.

187:    Output Parameter:
188: +  available - PETSC_TRUE if the val returned is valid
189: -  val - the norm 

191:    Notes:
192: $     NORM_1 denotes sum_i |x_i|
193: $     NORM_2 denotes sqrt(sum_i (x_i)^2)
194: $     NORM_INFINITY denotes max_i |x_i|

196:    Level: intermediate

198:    Performance Issues:
199: +    per-processor memory bandwidth
200: .    interprocessor latency
201: -    work load inbalance that causes certain processes to arrive much earlier than
202:      others

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

209:    Concepts: norm
210:    Concepts: vector^norm

212: .seealso: VecDot(), VecTDot(), VecNorm(), VecDotBegin(), VecDotEnd(), VecNorm()
213:           VecNormBegin(), VecNormEnd()

215: @*/
216: PetscErrorCode  VecNormAvailable(Vec x,NormType type,PetscTruth *available,PetscReal *val)
217: {


225:   *available = PETSC_FALSE;
226:   if (type!=NORM_1_AND_2) {
227:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[type],*val,*available);
228:   }
229:   return(0);
230: }

234: /*@
235:    VecNormalize - Normalizes a vector by 2-norm. 

237:    Collective on Vec

239:    Input Parameters:
240: +  x - the vector

242:    Output Parameter:
243: .  x - the normalized vector
244: -  val - the vector norm before normalization

246:    Level: intermediate

248:    Concepts: vector^normalizing
249:    Concepts: normalizing^vector

251: @*/
252: PetscErrorCode  VecNormalize(Vec x,PetscReal *val)
253: {
255:   PetscReal      norm;

260:   PetscLogEventBegin(VEC_Normalize,x,0,0,0);
261:   VecNorm(x,NORM_2,&norm);
262:   if (norm == 0.0) {
263:     PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
264:   } else if (norm != 1.0) {
265:     PetscScalar tmp = 1.0/norm;
266:     VecScale(x,tmp);
267:   }
268:   if (val) *val = norm;
269:   PetscLogEventEnd(VEC_Normalize,x,0,0,0);
270:   return(0);
271: }

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

278:    Collective on Vec

280:    Input Parameter:
281: .  x - the vector

283:    Output Parameters:
284: +  val - the maximum component
285: -  p - the location of val

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

290:    Level: intermediate

292:    Concepts: maximum^of vector
293:    Concepts: vector^maximum value

295: .seealso: VecNorm(), VecMin()
296: @*/
297: PetscErrorCode  VecMax(Vec x,PetscInt *p,PetscReal *val)
298: {

305:   PetscLogEventBegin(VEC_Max,x,0,0,0);
306:   (*x->ops->max)(x,p,val);
307:   PetscLogEventEnd(VEC_Max,x,0,0,0);
308:   return(0);
309: }

313: /*@
314:    VecMin - Determines the minimum vector component and its location.

316:    Collective on Vec

318:    Input Parameters:
319: .  x - the vector

321:    Output Parameter:
322: +  val - the minimum component
323: -  p - the location of val

325:    Level: intermediate

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

330:    Concepts: minimum^of vector
331:    Concepts: vector^minimum entry

333: .seealso: VecMax()
334: @*/
335: PetscErrorCode  VecMin(Vec x,PetscInt *p,PetscReal *val)
336: {

343:   PetscLogEventBegin(VEC_Min,x,0,0,0);
344:   (*x->ops->min)(x,p,val);
345:   PetscLogEventEnd(VEC_Min,x,0,0,0);
346:   return(0);
347: }

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

355:    Collective on Vec

357:    Input Parameters:
358: .  x, y - the vectors

360:    Output Parameter:
361: .  val - the dot product

363:    Notes for Users of Complex Numbers:
364:    For complex vectors, VecTDot() computes the indefinite form
365: $     val = (x,y) = y^T x,
366:    where y^T denotes the transpose of y.

368:    Use VecDot() for the inner product
369: $     val = (x,y) = y^H x,
370:    where y^H denotes the conjugate transpose of y.

372:    Level: intermediate

374:    Concepts: inner product^non-Hermitian
375:    Concepts: vector^inner product
376:    Concepts: non-Hermitian inner product

378: .seealso: VecDot(), VecMTDot()
379: @*/
380: PetscErrorCode  VecTDot(Vec x,Vec y,PetscScalar *val)
381: {


393:   PetscLogEventBegin(VEC_TDot,x,y,0,0);
394:   (*x->ops->tdot)(x,y,val);
395:   PetscLogEventEnd(VEC_TDot,x,y,0,0);
396:   return(0);
397: }

401: /*@
402:    VecScale - Scales a vector. 

404:    Collective on Vec

406:    Input Parameters:
407: +  x - the vector
408: -  alpha - the scalar

410:    Output Parameter:
411: .  x - the scaled vector

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

417:    Level: intermediate

419:    Concepts: vector^scaling
420:    Concepts: scaling^vector

422: @*/
423: PetscErrorCode  VecScale (Vec x, PetscScalar alpha)
424: {
425:   PetscReal      norms[4] = {0.0,0.0,0.0, 0.0};
426:   PetscTruth     flgs[4];
428:   PetscInt       i;

433:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
434:   PetscLogEventBegin(VEC_Scale,x,0,0,0);
435:   if (alpha != 1.0) {
436:     (*x->ops->scale)(x,alpha);

438:     /*
439:      * Update cached data
440:      */
441:     for (i=0; i<4; i++) {
442:       PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
443:     }

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

448:     for (i=0; i<4; i++) {
449:       if (flgs[i]) {
450:         PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
451:       }
452:     }
453:   }
454:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
455:   return(0);
456: }


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

464:    Collective on Vec

466:    Input Parameters:
467: +  x  - the vector
468: -  alpha - the scalar

470:    Output Parameter:
471: .  x  - the vector

473:    Note:
474:    For a vector of dimension n, VecSet() computes
475: $     x[i] = alpha, for i=1,...,n,
476:    so that all vector entries then equal the identical
477:    scalar value, alpha.  Use the more general routine
478:    VecSetValues() to set different vector entries.

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

483:    Level: beginner

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

487:    Concepts: vector^setting to constant

489: @*/
490: PetscErrorCode  VecSet(Vec x,PetscScalar alpha)
491: {
492:   PetscReal      val;

498:   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()");
499: #if defined (PETSC_USE_DEBUG)
500:  {
501:    PetscReal alpha_local,alpha_max;
502:    alpha_local = PetscAbsScalar(alpha);
503:    MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,((PetscObject)x)->comm);
504:    if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
505:  }
506: #endif

508:   PetscLogEventBegin(VEC_Set,x,0,0,0);
509:   (*x->ops->set)(x,alpha);
510:   PetscLogEventEnd(VEC_Set,x,0,0,0);

512:   /*
513:    * Update cached data
514:    */
515:   /* in general we consider this object touched */
516:   PetscObjectStateIncrease((PetscObject)x);

518:   /* however, norms can be simply set */
519:   val = PetscAbsScalar(alpha);
520:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
521:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
522:   val = sqrt((double)x->map->N) * val;
523:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
524:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
525:   return(0);
526: }


531: /*@
532:    VecAXPY - Computes y = alpha x + y. 

534:    Collective on Vec

536:    Input Parameters:
537: +  alpha - the scalar
538: -  x, y  - the vectors

540:    Output Parameter:
541: .  y - output vector

543:    Level: intermediate

545:    Notes: x and y must be different vectors

547:    Concepts: vector^BLAS
548:    Concepts: BLAS

550: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
551: @*/
552: PetscErrorCode  VecAXPY(Vec y,PetscScalar alpha,Vec x)
553: {


564:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
565:   (*y->ops->axpy)(y,alpha,x);
566:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
567:   PetscObjectStateIncrease((PetscObject)y);
568:   return(0);
569: }

573: /*@
574:    VecAXPBY - Computes y = alpha x + beta y. 

576:    Collective on Vec

578:    Input Parameters:
579: +  alpha,beta - the scalars
580: -  x, y  - the vectors

582:    Output Parameter:
583: .  y - output vector

585:    Level: intermediate

587:    Notes: x and y must be different vectors 

589:    Concepts: BLAS
590:    Concepts: vector^BLAS

592: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
593: @*/
594: PetscErrorCode  VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
595: {


606:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
607:   (*y->ops->axpby)(y,alpha,beta,x);
608:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
609:   PetscObjectStateIncrease((PetscObject)y);
610:   return(0);
611: }

615: /*@
616:    VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z

618:    Collective on Vec

620:    Input Parameters:
621: +  alpha,beta, gamma - the scalars
622: -  x, y, z  - the vectors

624:    Output Parameter:
625: .  z - output vector

627:    Level: intermediate

629:    Notes: x, y and z must be different vectors 

631:           alpha = 1 or gamma = 1 are handled as special cases

633:    Concepts: BLAS
634:    Concepts: vector^BLAS

636: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
637: @*/
638: PetscErrorCode  VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
639: {


654:   PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
655:   (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
656:   PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
657:   PetscObjectStateIncrease((PetscObject)y);
658:   return(0);
659: }

663: /*@
664:    VecAYPX - Computes y = x + alpha y.

666:    Collective on Vec

668:    Input Parameters:
669: +  alpha - the scalar
670: -  x, y  - the vectors

672:    Output Parameter:
673: .  y - output vector

675:    Level: intermediate

677:    Notes: x and y must be different vectors

679:    Concepts: vector^BLAS
680:    Concepts: BLAS

682: .seealso: VecAXPY(), VecWAXPY()
683: @*/
684: PetscErrorCode  VecAYPX(Vec y,PetscScalar alpha,Vec x)
685: {


694:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
695:    (*y->ops->aypx)(y,alpha,x);
696:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
697:   PetscObjectStateIncrease((PetscObject)y);
698:   return(0);
699: }


704: /*@
705:    VecWAXPY - Computes w = alpha x + y.

707:    Collective on Vec

709:    Input Parameters:
710: +  alpha - the scalar
711: -  x, y  - the vectors

713:    Output Parameter:
714: .  w - the result

716:    Level: intermediate

718:    Notes: Neither the vector x or y can be the same as vector w

720:    Concepts: vector^BLAS
721:    Concepts: BLAS

723: .seealso: VecAXPY(), VecAYPX(), VecAXPBY()
724: @*/
725: PetscErrorCode  VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
726: {

740:   if (w == y) SETERRQ(PETSC_ERR_SUP,"Result vector w cannot be same as input vector y, suggest VecAXPY()");
741:   if (w == x) SETERRQ(PETSC_ERR_SUP,"Result vector w cannot be same as input vector x, suggest VecAYPX()");

743:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
744:    (*w->ops->waxpy)(w,alpha,x,y);
745:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
746:   PetscObjectStateIncrease((PetscObject)w);
747:   return(0);
748: }


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

756:    Not Collective

758:    Input Parameters:
759: +  x - vector to insert in
760: .  ni - number of elements to add
761: .  ix - indices where to add
762: .  y - array of values
763: -  iora - either INSERT_VALUES or ADD_VALUES, where
764:    ADD_VALUES adds values to any existing entries, and
765:    INSERT_VALUES replaces existing entries with new values

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

770:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
771:    options cannot be mixed without intervening calls to the assembly
772:    routines.

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

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

779:    If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE), 
780:    negative indices may be passed in ix. These rows are 
781:    simply ignored. This allows easily inserting element load matrices
782:    with homogeneous Dirchlet boundary conditions that you don't want represented
783:    in the vector.

785:    Level: beginner

787:    Concepts: vector^setting values

789: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
790:            VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
791: @*/
792: PetscErrorCode  VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
793: {

801:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
802:   (*x->ops->setvalues)(x,ni,ix,y,iora);
803:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
804:   PetscObjectStateIncrease((PetscObject)x);
805:   return(0);
806: }

810: /*@
811:    VecGetValues - Gets values from certain locations of a vector. Currently 
812:           can only get values on the same processor

814:     Collective on Vec
815:  
816:    Input Parameters:
817: +  x - vector to get values from
818: .  ni - number of elements to get
819: -  ix - indices where to get them from (in global 1d numbering)

821:    Output Parameter:
822: .   y - array of values

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

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

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

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

833:    If you call VecSetOption(x, VEC_IGNORE_NEGATIVE_INDICES,PETSC_TRUE),
834:    negative indices may be passed in ix. These rows are
835:    simply ignored.

837:    Level: beginner

839:    Concepts: vector^getting values

841: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
842:            VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
843: @*/
844: PetscErrorCode  VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
845: {

853:   (*x->ops->getvalues)(x,ni,ix,y);
854:   return(0);
855: }

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

862:    Not Collective

864:    Input Parameters:
865: +  x - vector to insert in
866: .  ni - number of blocks to add
867: .  ix - indices where to add in block count, rather than element count
868: .  y - array of values
869: -  iora - either INSERT_VALUES or ADD_VALUES, where
870:    ADD_VALUES adds values to any existing entries, and
871:    INSERT_VALUES replaces existing entries with new values

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

877:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
878:    options cannot be mixed without intervening calls to the assembly
879:    routines.

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

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

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

891:    Level: intermediate

893:    Concepts: vector^setting values blocked

895: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
896:            VecSetValues()
897: @*/
898: PetscErrorCode  VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
899: {

907:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
908:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
909:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
910:   PetscObjectStateIncrease((PetscObject)x);
911:   return(0);
912: }


917: /*@
918:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
919:    using a local ordering of the nodes. 

921:    Not Collective

923:    Input Parameters:
924: +  x - vector to insert in
925: .  ni - number of elements to add
926: .  ix - indices where to add
927: .  y - array of values
928: -  iora - either INSERT_VALUES or ADD_VALUES, where
929:    ADD_VALUES adds values to any existing entries, and
930:    INSERT_VALUES replaces existing entries with new values

932:    Level: intermediate

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

937:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
938:    options cannot be mixed without intervening calls to the assembly
939:    routines.

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

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

946:    Concepts: vector^setting values with local numbering

948: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
949:            VecSetValuesBlockedLocal()
950: @*/
951: PetscErrorCode  VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
952: {
954:   PetscInt       lixp[128],*lix = lixp;


962:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
963:   if (!x->ops->setvalueslocal) {
964:     if (!x->mapping) {
965:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
966:     }
967:     if (ni > 128) {
968:       PetscMalloc(ni*sizeof(PetscInt),&lix);
969:     }
970:     ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
971:     (*x->ops->setvalues)(x,ni,lix,y,iora);
972:     if (ni > 128) {
973:       PetscFree(lix);
974:     }
975:   } else {
976:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
977:   }
978:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
979:   PetscObjectStateIncrease((PetscObject)x);
980:   return(0);
981: }

985: /*@
986:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
987:    using a local ordering of the nodes. 

989:    Not Collective

991:    Input Parameters:
992: +  x - vector to insert in
993: .  ni - number of blocks to add
994: .  ix - indices where to add in block count, not element count
995: .  y - array of values
996: -  iora - either INSERT_VALUES or ADD_VALUES, where
997:    ADD_VALUES adds values to any existing entries, and
998:    INSERT_VALUES replaces existing entries with new values

1000:    Level: intermediate

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

1006:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
1007:    options cannot be mixed without intervening calls to the assembly
1008:    routines.

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

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


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

1018: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
1019:            VecSetLocalToGlobalMappingBlock()
1020: @*/
1021: PetscErrorCode  VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
1022: {
1024:   PetscInt       lixp[128],*lix = lixp;

1031:   if (!x->bmapping) {
1032:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlock()");
1033:   }
1034:   if (ni > 128) {
1035:     PetscMalloc(ni*sizeof(PetscInt),&lix);
1036:   }

1038:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
1039:   ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
1040:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
1041:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
1042:   if (ni > 128) {
1043:     PetscFree(lix);
1044:   }
1045:   PetscObjectStateIncrease((PetscObject)x);
1046:   return(0);
1047: }



1053: /*@
1054:    VecMTDot - Computes indefinite vector multiple dot products. 
1055:    That is, it does NOT use the complex conjugate.

1057:    Collective on Vec

1059:    Input Parameters:
1060: +  x - one vector
1061: .  nv - number of vectors
1062: -  y - array of vectors.  Note that vectors are pointers

1064:    Output Parameter:
1065: .  val - array of the dot products

1067:    Notes for Users of Complex Numbers:
1068:    For complex vectors, VecMTDot() computes the indefinite form
1069: $      val = (x,y) = y^T x,
1070:    where y^T denotes the transpose of y.

1072:    Use VecMDot() for the inner product
1073: $      val = (x,y) = y^H x,
1074:    where y^H denotes the conjugate transpose of y.

1076:    Level: intermediate

1078:    Concepts: inner product^multiple
1079:    Concepts: vector^multiple inner products

1081: .seealso: VecMDot(), VecTDot()
1082: @*/
1083: PetscErrorCode  VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1084: {


1097:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1098:   (*x->ops->mtdot)(x,nv,y,val);
1099:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1100:   return(0);
1101: }

1105: /*@
1106:    VecMDot - Computes vector multiple dot products. 

1108:    Collective on Vec

1110:    Input Parameters:
1111: +  x - one vector
1112: .  nv - number of vectors
1113: -  y - array of vectors. 

1115:    Output Parameter:
1116: .  val - array of the dot products (does not allocate the array)

1118:    Notes for Users of Complex Numbers:
1119:    For complex vectors, VecMDot() computes 
1120: $     val = (x,y) = y^H x,
1121:    where y^H denotes the conjugate transpose of y.

1123:    Use VecMTDot() for the indefinite form
1124: $     val = (x,y) = y^T x,
1125:    where y^T denotes the transpose of y.

1127:    Level: intermediate

1129:    Concepts: inner product^multiple
1130:    Concepts: vector^multiple inner products

1132: .seealso: VecMTDot(), VecDot()
1133: @*/
1134: PetscErrorCode  VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1135: {

1140:   if (!nv) return(0);
1141:   if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);

1150:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1151:   (*x->ops->mdot)(x,nv,y,val);
1152:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1153:   return(0);
1154: }

1158: /*@
1159:    VecMAXPY - Computes y = y + sum alpha[j] x[j]

1161:    Collective on Vec

1163:    Input Parameters:
1164: +  nv - number of scalars and x-vectors
1165: .  alpha - array of scalars
1166: .  y - one vector
1167: -  x - array of vectors

1169:    Level: intermediate

1171:    Concepts: BLAS

1173: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1174: @*/
1175: PetscErrorCode  VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1176: {

1181:   if (!nv) return(0);
1182:   if (nv < 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Number of vectors (given %D) cannot be negative",nv);

1191:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1192:   (*y->ops->maxpy)(y,nv,alpha,x);
1193:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1194:   PetscObjectStateIncrease((PetscObject)y);
1195:   return(0);
1196: }

1198: /*MC
1199:    VecGetArray - Returns a pointer to a contiguous array that contains this 
1200:    processor's portion of the vector data. For the standard PETSc
1201:    vectors, VecGetArray() returns a pointer to the local data array and
1202:    does not use any copies. If the underlying vector data is not stored
1203:    in a contiquous array this routine will copy the data to a contiquous
1204:    array and return a pointer to that. You MUST call VecRestoreArray() 
1205:    when you no longer need access to the array.

1207:    Synopsis:
1208:    PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])

1210:    Not Collective

1212:    Input Parameter:
1213: .  x - the vector

1215:    Output Parameter:
1216: .  a - location to put pointer to the array

1218:    Fortran Note:
1219:    This routine is used differently from Fortran 77
1220: $    Vec         x
1221: $    PetscScalar x_array(1)
1222: $    PetscOffset i_x
1223: $    PetscErrorCode ierr
1224: $       call VecGetArray(x,x_array,i_x,ierr)
1225: $
1226: $   Access first local entry in vector with
1227: $      value = x_array(i_x + 1)
1228: $
1229: $      ...... other code
1230: $       call VecRestoreArray(x,x_array,i_x,ierr)
1231:    For Fortran 90 see VecGetArrayF90()

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

1236:    Level: beginner

1238:    Concepts: vector^accessing local values

1240: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1241: M*/
1244: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
1245: {

1252:   (*x->ops->getarray)(x,a);
1253:   return(0);
1254: }


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

1264:    Not Collective

1266:    Input Parameter:
1267: +  x - the vectors
1268: -  n - the number of vectors

1270:    Output Parameter:
1271: .  a - location to put pointer to the array

1273:    Fortran Note:
1274:    This routine is not supported in Fortran.

1276:    Level: intermediate

1278: .seealso: VecGetArray(), VecRestoreArrays()
1279: @*/
1280: PetscErrorCode  VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1281: {
1283:   PetscInt       i;
1284:   PetscScalar    **q;

1290:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
1291:   PetscMalloc(n*sizeof(PetscScalar*),&q);
1292:   for (i=0; i<n; ++i) {
1293:     VecGetArray(x[i],&q[i]);
1294:   }
1295:   *a = q;
1296:   return(0);
1297: }

1301: /*@C
1302:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1303:    has been called.

1305:    Not Collective

1307:    Input Parameters:
1308: +  x - the vector
1309: .  n - the number of vectors
1310: -  a - location of pointer to arrays obtained from VecGetArrays()

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

1318:    Fortran Note:
1319:    This routine is not supported in Fortran.

1321:    Level: intermediate

1323: .seealso: VecGetArrays(), VecRestoreArray()
1324: @*/
1325: PetscErrorCode  VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1326: {
1328:   PetscInt       i;
1329:   PetscScalar    **q = *a;


1336:   for(i=0;i<n;++i) {
1337:     VecRestoreArray(x[i],&q[i]);
1338:  }
1339:   PetscFree(q);
1340:   return(0);
1341: }

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

1346:    Not Collective

1348:    Synopsis:
1349:    PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])

1351:    Input Parameters:
1352: +  x - the vector
1353: -  a - location of pointer to array obtained from VecGetArray()

1355:    Level: beginner

1357:    Notes:
1358:    For regular PETSc vectors this routine does not involve any copies. For
1359:    any special vectors that do not store local vector data in a contiguous
1360:    array, this routine will copy the data back into the underlying 
1361:    vector data structure from the array obtained with VecGetArray().

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

1367:    Fortran Note:
1368:    This routine is used differently from Fortran 77
1369: $    Vec         x
1370: $    PetscScalar x_array(1)
1371: $    PetscOffset i_x
1372: $    PetscErrorCode ierr
1373: $       call VecGetArray(x,x_array,i_x,ierr)
1374: $
1375: $   Access first local entry in vector with
1376: $      value = x_array(i_x + 1)
1377: $
1378: $      ...... other code
1379: $       call VecRestoreArray(x,x_array,i_x,ierr)

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

1385: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
1386: M*/
1389: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
1390: {

1397: #if defined(PETSC_USE_DEBUG)
1398:   CHKMEMQ;
1399: #endif
1400:   if (x->ops->restorearray) {
1401:     (*x->ops->restorearray)(x,a);
1402:   }
1403:   PetscObjectStateIncrease((PetscObject)x);
1404:   return(0);
1405: }


1410: /*@
1411:    VecPlaceArray - Allows one to replace the array in a vector with an
1412:    array provided by the user. This is useful to avoid copying an array
1413:    into a vector.

1415:    Not Collective

1417:    Input Parameters:
1418: +  vec - the vector
1419: -  array - the array

1421:    Notes:
1422:    You can return to the original array with a call to VecResetArray()

1424:    Level: developer

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

1428: @*/
1429: PetscErrorCode  VecPlaceArray(Vec vec,const PetscScalar array[])
1430: {

1437:   if (vec->ops->placearray) {
1438:     (*vec->ops->placearray)(vec,array);
1439:   } else {
1440:     SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
1441:   }
1442:   PetscObjectStateIncrease((PetscObject)vec);
1443:   return(0);
1444: }


1449: /*@C
1450:    VecReplaceArray - Allows one to replace the array in a vector with an
1451:    array provided by the user. This is useful to avoid copying an array
1452:    into a vector.

1454:    Not Collective

1456:    Input Parameters:
1457: +  vec - the vector
1458: -  array - the array

1460:    Notes:
1461:    This permanently replaces the array and frees the memory associated
1462:    with the old array.

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

1467:    Not supported from Fortran

1469:    Level: developer

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

1473: @*/
1474: PetscErrorCode  VecReplaceArray(Vec vec,const PetscScalar array[])
1475: {

1481:   if (vec->ops->replacearray) {
1482:     (*vec->ops->replacearray)(vec,array);
1483:  } else {
1484:     SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
1485:   }
1486:   PetscObjectStateIncrease((PetscObject)vec);
1487:   return(0);
1488: }

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

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

1497:     Collective on Vec

1499:     Input Parameters:
1500: +   x - a vector to mimic
1501: -   n - the number of vectors to obtain

1503:     Output Parameters:
1504: +   y - Fortran90 pointer to the array of vectors
1505: -   ierr - error code

1507:     Example of Usage: 
1508: .vb
1509:     Vec x
1510:     Vec, pointer :: y(:)
1511:     ....
1512:     call VecDuplicateVecsF90(x,2,y,ierr)
1513:     call VecSet(y(2),alpha,ierr)
1514:     call VecSet(y(2),alpha,ierr)
1515:     ....
1516:     call VecDestroyVecsF90(y,2,ierr)
1517: .ve

1519:     Notes:
1520:     Not yet supported for all F90 compilers

1522:     Use VecDestroyVecsF90() to free the space.

1524:     Level: beginner

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

1528: M*/

1530: /*MC
1531:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
1532:     VecGetArrayF90().

1534:     Synopsis:
1535:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

1537:     Not collective

1539:     Input Parameters:
1540: +   x - vector
1541: -   xx_v - the Fortran90 pointer to the array

1543:     Output Parameter:
1544: .   ierr - error code

1546:     Example of Usage: 
1547: .vb
1548:     PetscScalar, pointer :: xx_v(:)
1549:     ....
1550:     call VecGetArrayF90(x,xx_v,ierr)
1551:     a = xx_v(3)
1552:     call VecRestoreArrayF90(x,xx_v,ierr)
1553: .ve
1554:    
1555:     Level: beginner

1557: .seealso:  VecGetArrayF90(), VecGetArray(), VecRestoreArray(), UsingFortran

1559: M*/

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

1564:     Synopsis:
1565:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

1567:     Input Parameters:
1568: +   x - pointer to array of vector pointers
1569: -   n - the number of vectors previously obtained

1571:     Output Parameter:
1572: .   ierr - error code

1574:     Notes:
1575:     Not yet supported for all F90 compilers

1577:     Level: beginner

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

1581: M*/

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

1589:     Synopsis:
1590:     VecGetArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

1592:     Not Collective 

1594:     Input Parameter:
1595: .   x - vector

1597:     Output Parameters:
1598: +   xx_v - the Fortran90 pointer to the array
1599: -   ierr - error code

1601:     Example of Usage: 
1602: .vb
1603:     PetscScalar, pointer :: xx_v(:)
1604:     ....
1605:     call VecGetArrayF90(x,xx_v,ierr)
1606:     a = xx_v(3)
1607:     call VecRestoreArrayF90(x,xx_v,ierr)
1608: .ve

1610:     Level: beginner

1612: .seealso:  VecRestoreArrayF90(), VecGetArray(), VecRestoreArray(), UsingFortran

1614: M*/


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

1624:    Not Collective

1626:    Input Parameter:
1627: +  x - the vector
1628: .  m - first dimension of two dimensional array
1629: .  n - second dimension of two dimensional array
1630: .  mstart - first index you will use in first coordinate direction (often 0)
1631: -  nstart - first index in the second coordinate direction (often 0)

1633:    Output Parameter:
1634: .  a - location to put pointer to the array

1636:    Level: developer

1638:   Notes:
1639:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
1640:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1641:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1642:    the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
1643:    
1644:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1648: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1649:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1650:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1651: @*/
1652: PetscErrorCode  VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1653: {
1655:   PetscInt       i,N;
1656:   PetscScalar    *aa;

1662:   VecGetLocalSize(x,&N);
1663:   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);
1664:   VecGetArray(x,&aa);

1666:   PetscMalloc(m*sizeof(PetscScalar*),a);
1667:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
1668:   *a -= mstart;
1669:   return(0);
1670: }

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

1677:    Not Collective

1679:    Input Parameters:
1680: +  x - the vector
1681: .  m - first dimension of two dimensional array
1682: .  n - second dimension of the two dimensional array
1683: .  mstart - first index you will use in first coordinate direction (often 0)
1684: .  nstart - first index in the second coordinate direction (often 0)
1685: -  a - location of pointer to array obtained from VecGetArray2d()

1687:    Level: developer

1689:    Notes:
1690:    For regular PETSc vectors this routine does not involve any copies. For
1691:    any special vectors that do not store local vector data in a contiguous
1692:    array, this routine will copy the data back into the underlying 
1693:    vector data structure from the array obtained with VecGetArray().

1695:    This routine actually zeros out the a pointer. 

1697: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1698:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1699:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1700: @*/
1701: PetscErrorCode  VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1702: {
1704:   void           *dummy;

1710:   dummy = (void*)(*a + mstart);
1711:   PetscFree(dummy);
1712:   VecRestoreArray(x,PETSC_NULL);
1713:   return(0);
1714: }

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

1723:    Not Collective

1725:    Input Parameter:
1726: +  x - the vector
1727: .  m - first dimension of two dimensional array
1728: -  mstart - first index you will use in first coordinate direction (often 0)

1730:    Output Parameter:
1731: .  a - location to put pointer to the array

1733:    Level: developer

1735:   Notes:
1736:    For a vector obtained from DACreateLocalVector() mstart are likely
1737:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1738:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
1739:    
1740:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

1742: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1743:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1744:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1745: @*/
1746: PetscErrorCode  VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1747: {
1749:   PetscInt       N;

1755:   VecGetLocalSize(x,&N);
1756:   if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
1757:   VecGetArray(x,a);
1758:   *a  -= mstart;
1759:   return(0);
1760: }

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

1767:    Not Collective

1769:    Input Parameters:
1770: +  x - the vector
1771: .  m - first dimension of two dimensional array
1772: .  mstart - first index you will use in first coordinate direction (often 0)
1773: -  a - location of pointer to array obtained from VecGetArray21()

1775:    Level: developer

1777:    Notes:
1778:    For regular PETSc vectors this routine does not involve any copies. For
1779:    any special vectors that do not store local vector data in a contiguous
1780:    array, this routine will copy the data back into the underlying 
1781:    vector data structure from the array obtained with VecGetArray1d().

1783:    This routine actually zeros out the a pointer. 

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

1787: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1788:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1789:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
1790: @*/
1791: PetscErrorCode  VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1792: {

1798:   VecRestoreArray(x,PETSC_NULL);
1799:   return(0);
1800: }


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

1810:    Not Collective

1812:    Input Parameter:
1813: +  x - the vector
1814: .  m - first dimension of three dimensional array
1815: .  n - second dimension of three dimensional array
1816: .  p - third dimension of three dimensional array
1817: .  mstart - first index you will use in first coordinate direction (often 0)
1818: .  nstart - first index in the second coordinate direction (often 0)
1819: -  pstart - first index in the third coordinate direction (often 0)

1821:    Output Parameter:
1822: .  a - location to put pointer to the array

1824:    Level: developer

1826:   Notes:
1827:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1828:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1829:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1830:    the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
1831:    
1832:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1836: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1837:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1838:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1839: @*/
1840: PetscErrorCode  VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1841: {
1843:   PetscInt       i,N,j;
1844:   PetscScalar    *aa,**b;

1850:   VecGetLocalSize(x,&N);
1851:   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);
1852:   VecGetArray(x,&aa);

1854:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
1855:   b    = (PetscScalar **)((*a) + m);
1856:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
1857:   for (i=0; i<m; i++) {
1858:     for (j=0; j<n; j++) {
1859:       b[i*n+j] = aa + i*n*p + j*p - pstart;
1860:     }
1861:   }
1862:   *a -= mstart;
1863:   return(0);
1864: }

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

1871:    Not Collective

1873:    Input Parameters:
1874: +  x - the vector
1875: .  m - first dimension of three dimensional array
1876: .  n - second dimension of the three dimensional array
1877: .  p - third dimension of the three dimensional array
1878: .  mstart - first index you will use in first coordinate direction (often 0)
1879: .  nstart - first index in the second coordinate direction (often 0)
1880: .  pstart - first index in the third coordinate direction (often 0)
1881: -  a - location of pointer to array obtained from VecGetArray3d()

1883:    Level: developer

1885:    Notes:
1886:    For regular PETSc vectors this routine does not involve any copies. For
1887:    any special vectors that do not store local vector data in a contiguous
1888:    array, this routine will copy the data back into the underlying 
1889:    vector data structure from the array obtained with VecGetArray().

1891:    This routine actually zeros out the a pointer. 

1893: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1894:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1895:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1896: @*/
1897: PetscErrorCode  VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1898: {
1900:   void           *dummy;

1906:   dummy = (void*)(*a + mstart);
1907:   PetscFree(dummy);
1908:   VecRestoreArray(x,PETSC_NULL);
1909:   return(0);
1910: }

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

1919:    Not Collective

1921:    Input Parameter:
1922: +  x - the vector
1923: .  m - first dimension of four dimensional array
1924: .  n - second dimension of four dimensional array
1925: .  p - third dimension of four dimensional array
1926: .  q - fourth dimension of four dimensional array
1927: .  mstart - first index you will use in first coordinate direction (often 0)
1928: .  nstart - first index in the second coordinate direction (often 0)
1929: .  pstart - first index in the third coordinate direction (often 0)
1930: -  qstart - first index in the fourth coordinate direction (often 0)

1932:    Output Parameter:
1933: .  a - location to put pointer to the array

1935:    Level: beginner

1937:   Notes:
1938:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1939:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1940:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1941:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
1942:    
1943:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1947: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1948:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1949:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1950: @*/
1951: PetscErrorCode  VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1952: {
1954:   PetscInt       i,N,j,k;
1955:   PetscScalar    *aa,***b,**c;

1961:   VecGetLocalSize(x,&N);
1962:   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);
1963:   VecGetArray(x,&aa);

1965:   PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
1966:   b    = (PetscScalar ***)((*a) + m);
1967:   c    = (PetscScalar **)(b + m*n);
1968:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
1969:   for (i=0; i<m; i++) {
1970:     for (j=0; j<n; j++) {
1971:       b[i*n+j] = c + i*n*p + j*p - pstart;
1972:     }
1973:   }
1974:   for (i=0; i<m; i++) {
1975:     for (j=0; j<n; j++) {
1976:       for (k=0; k<p; k++) {
1977:         c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
1978:       }
1979:     }
1980:   }
1981:   *a -= mstart;
1982:   return(0);
1983: }

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

1990:    Not Collective

1992:    Input Parameters:
1993: +  x - the vector
1994: .  m - first dimension of four dimensional array
1995: .  n - second dimension of the four dimensional array
1996: .  p - third dimension of the four dimensional array
1997: .  q - fourth dimension of the four dimensional array
1998: .  mstart - first index you will use in first coordinate direction (often 0)
1999: .  nstart - first index in the second coordinate direction (often 0)
2000: .  pstart - first index in the third coordinate direction (often 0)
2001: .  qstart - first index in the fourth coordinate direction (often 0)
2002: -  a - location of pointer to array obtained from VecGetArray4d()

2004:    Level: beginner

2006:    Notes:
2007:    For regular PETSc vectors this routine does not involve any copies. For
2008:    any special vectors that do not store local vector data in a contiguous
2009:    array, this routine will copy the data back into the underlying 
2010:    vector data structure from the array obtained with VecGetArray().

2012:    This routine actually zeros out the a pointer. 

2014: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
2015:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
2016:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
2017: @*/
2018: PetscErrorCode  VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
2019: {
2021:   void           *dummy;

2027:   dummy = (void*)(*a + mstart);
2028:   PetscFree(dummy);
2029:   VecRestoreArray(x,PETSC_NULL);
2030:   return(0);
2031: }