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(), 
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:    VecNormalize - Normalizes a vector by 2-norm. 

179:    Collective on Vec

181:    Input Parameters:
182: +  x - the vector

184:    Output Parameter:
185: .  x - the normalized vector
186: -  val - the vector norm before normalization

188:    Level: intermediate

190:    Concepts: vector^normalizing
191:    Concepts: normalizing^vector

193: @*/
194: PetscErrorCode  VecNormalize(Vec x,PetscReal *val)
195: {
197:   PetscReal      norm;

202:   PetscLogEventBegin(VEC_Normalize,x,0,0,0);
203:   VecNorm(x,NORM_2,&norm);
204:   if (!norm) {
205:     PetscInfo(x,"Vector of zero norm can not be normalized; Returning only the zero norm\n");
206:   } else if (norm != 1.0) {
207:     PetscScalar tmp = 1.0/norm;
208:     VecScale(x,tmp);
209:   }
210:   if (val) *val = norm;
211:   PetscLogEventEnd(VEC_Normalize,x,0,0,0);
212:   return(0);
213: }

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

220:    Collective on Vec

222:    Input Parameter:
223: .  x - the vector

225:    Output Parameters:
226: +  val - the maximum component
227: -  p - the location of val

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

232:    Level: intermediate

234:    Concepts: maximum^of vector
235:    Concepts: vector^maximum value

237: .seealso: VecNorm(), VecMin()
238: @*/
239: PetscErrorCode  VecMax(Vec x,PetscInt *p,PetscReal *val)
240: {

247:   PetscLogEventBegin(VEC_Max,x,0,0,0);
248:   (*x->ops->max)(x,p,val);
249:   PetscLogEventEnd(VEC_Max,x,0,0,0);
250:   return(0);
251: }

255: /*@
256:    VecMin - Determines the minimum vector component and its location.

258:    Collective on Vec

260:    Input Parameters:
261: .  x - the vector

263:    Output Parameter:
264: +  val - the minimum component
265: -  p - the location of val

267:    Level: intermediate

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

272:    Concepts: minimum^of vector
273:    Concepts: vector^minimum entry

275: .seealso: VecMax()
276: @*/
277: PetscErrorCode  VecMin(Vec x,PetscInt *p,PetscReal *val)
278: {

285:   PetscLogEventBegin(VEC_Min,x,0,0,0);
286:   (*x->ops->min)(x,p,val);
287:   PetscLogEventEnd(VEC_Min,x,0,0,0);
288:   return(0);
289: }

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

297:    Collective on Vec

299:    Input Parameters:
300: .  x, y - the vectors

302:    Output Parameter:
303: .  val - the dot product

305:    Notes for Users of Complex Numbers:
306:    For complex vectors, VecTDot() computes the indefinite form
307: $     val = (x,y) = y^T x,
308:    where y^T denotes the transpose of y.

310:    Use VecDot() for the inner product
311: $     val = (x,y) = y^H x,
312:    where y^H denotes the conjugate transpose of y.

314:    Level: intermediate

316:    Concepts: inner product^non-Hermitian
317:    Concepts: vector^inner product
318:    Concepts: non-Hermitian inner product

320: .seealso: VecDot(), VecMTDot()
321: @*/
322: PetscErrorCode  VecTDot(Vec x,Vec y,PetscScalar *val)
323: {


335:   PetscLogEventBegin(VEC_TDot,x,y,0,0);
336:   (*x->ops->tdot)(x,y,val);
337:   PetscLogEventEnd(VEC_TDot,x,y,0,0);
338:   return(0);
339: }

343: /*@
344:    VecScale - Scales a vector. 

346:    Collective on Vec

348:    Input Parameters:
349: +  x - the vector
350: -  alpha - the scalar

352:    Output Parameter:
353: .  x - the scaled vector

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

359:    Level: intermediate

361:    Concepts: vector^scaling
362:    Concepts: scaling^vector

364: @*/
365: PetscErrorCode  VecScale (Vec x, PetscScalar alpha)
366: {
367:   PetscReal      norms[4] = {0.0,0.0,0.0, 0.0};
368:   PetscTruth     flgs[4];
370:   PetscInt       i;

375:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
376:   PetscLogEventBegin(VEC_Scale,x,0,0,0);
377:   if (alpha != 1.0) {
378:     (*x->ops->scale)(x,alpha);

380:     /*
381:      * Update cached data
382:      */
383:     for (i=0; i<4; i++) {
384:       PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
385:     }

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

390:     for (i=0; i<4; i++) {
391:       if (flgs[i]) {
392:         PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],PetscAbsScalar(alpha)*norms[i]);
393:       }
394:     }
395:   }
396:   PetscLogEventEnd(VEC_Scale,x,0,0,0);
397:   return(0);
398: }


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

406:    Collective on Vec

408:    Input Parameters:
409: +  x  - the vector
410: -  alpha - the scalar

412:    Output Parameter:
413: .  x  - the vector

415:    Note:
416:    For a vector of dimension n, VecSet() computes
417: $     x[i] = alpha, for i=1,...,n,
418:    so that all vector entries then equal the identical
419:    scalar value, alpha.  Use the more general routine
420:    VecSetValues() to set different vector entries.

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

425:    Level: beginner

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

429:    Concepts: vector^setting to constant

431: @*/
432: PetscErrorCode  VecSet(Vec x,PetscScalar alpha)
433: {
434:   PetscReal      val;

440:   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()");
441: #if defined (PETSC_USE_DEBUG)
442:  {
443:    PetscReal alpha_local,alpha_max;
444:    alpha_local = PetscAbsScalar(alpha);
445:    MPI_Allreduce(&alpha_local,&alpha_max,1,MPIU_REAL,MPI_MAX,((PetscObject)x)->comm);
446:    if (alpha_local != alpha_max) SETERRQ(PETSC_ERR_ARG_WRONG,"Same value should be used across all processors");
447:  }
448: #endif

450:   PetscLogEventBegin(VEC_Set,x,0,0,0);
451:   (*x->ops->set)(x,alpha);
452:   PetscLogEventEnd(VEC_Set,x,0,0,0);

454:   /*
455:    * Update cached data
456:    */
457:   /* in general we consider this object touched */
458:   PetscObjectStateIncrease((PetscObject)x);

460:   /* however, norms can be simply set */
461:   val = PetscAbsScalar(alpha);
462:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_1],x->map->N * val);
463:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_INFINITY],val);
464:   val = sqrt((double)x->map->N) * val;
465:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_2],val);
466:   PetscObjectComposedDataSetReal((PetscObject)x,NormIds[NORM_FROBENIUS],val);
467:   return(0);
468: }


473: /*@
474:    VecAXPY - Computes y = alpha x + y. 

476:    Collective on Vec

478:    Input Parameters:
479: +  alpha - the scalar
480: -  x, y  - the vectors

482:    Output Parameter:
483: .  y - output vector

485:    Level: intermediate

487:    Notes: x and y must be different vectors

489:    Concepts: vector^BLAS
490:    Concepts: BLAS

492: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY()
493: @*/
494: PetscErrorCode  VecAXPY(Vec y,PetscScalar alpha,Vec x)
495: {


506:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
507:   (*y->ops->axpy)(y,alpha,x);
508:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
509:   PetscObjectStateIncrease((PetscObject)y);
510:   return(0);
511: }

515: /*@
516:    VecAXPBY - Computes y = alpha x + beta y. 

518:    Collective on Vec

520:    Input Parameters:
521: +  alpha,beta - the scalars
522: -  x, y  - the vectors

524:    Output Parameter:
525: .  y - output vector

527:    Level: intermediate

529:    Notes: x and y must be different vectors 

531:    Concepts: BLAS
532:    Concepts: vector^BLAS

534: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
535: @*/
536: PetscErrorCode  VecAXPBY(Vec y,PetscScalar alpha,PetscScalar beta,Vec x)
537: {


548:   PetscLogEventBegin(VEC_AXPY,x,y,0,0);
549:   (*y->ops->axpby)(y,alpha,beta,x);
550:   PetscLogEventEnd(VEC_AXPY,x,y,0,0);
551:   PetscObjectStateIncrease((PetscObject)y);
552:   return(0);
553: }

557: /*@
558:    VecAXPBYPCZ - Computes z = alpha x + beta y + gamma z

560:    Collective on Vec

562:    Input Parameters:
563: +  alpha,beta, gamma - the scalars
564: -  x, y, z  - the vectors

566:    Output Parameter:
567: .  z - output vector

569:    Level: intermediate

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

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

575:    Concepts: BLAS
576:    Concepts: vector^BLAS

578: .seealso: VecAYPX(), VecMAXPY(), VecWAXPY(), VecAXPY()
579: @*/
580: PetscErrorCode  VecAXPBYPCZ(Vec z,PetscScalar alpha,PetscScalar beta,PetscScalar gamma,Vec x,Vec y)
581: {


596:   PetscLogEventBegin(VEC_AXPBYPCZ,x,y,z,0);
597:   (*y->ops->axpbypcz)(z,alpha,beta,gamma,x,y);
598:   PetscLogEventEnd(VEC_AXPBYPCZ,x,y,z,0);
599:   PetscObjectStateIncrease((PetscObject)y);
600:   return(0);
601: }

605: /*@
606:    VecAYPX - Computes y = x + alpha y.

608:    Collective on Vec

610:    Input Parameters:
611: +  alpha - the scalar
612: -  x, y  - the vectors

614:    Output Parameter:
615: .  y - output vector

617:    Level: intermediate

619:    Notes: x and y must be different vectors

621:    Concepts: vector^BLAS
622:    Concepts: BLAS

624: .seealso: VecAXPY(), VecWAXPY()
625: @*/
626: PetscErrorCode  VecAYPX(Vec y,PetscScalar alpha,Vec x)
627: {


638:   PetscLogEventBegin(VEC_AYPX,x,y,0,0);
639:    (*y->ops->aypx)(y,alpha,x);
640:   PetscLogEventEnd(VEC_AYPX,x,y,0,0);
641:   PetscObjectStateIncrease((PetscObject)y);
642:   return(0);
643: }


648: /*@
649:    VecWAXPY - Computes w = alpha x + y.

651:    Collective on Vec

653:    Input Parameters:
654: +  alpha - the scalar
655: -  x, y  - the vectors

657:    Output Parameter:
658: .  w - the result

660:    Level: intermediate

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

664:    Concepts: vector^BLAS
665:    Concepts: BLAS

667: .seealso: VecAXPY(), VecAYPX(), VecAXPBY()
668: @*/
669: PetscErrorCode  VecWAXPY(Vec w,PetscScalar alpha,Vec x,Vec y)
670: {


685:   PetscLogEventBegin(VEC_WAXPY,x,y,w,0);
686:    (*w->ops->waxpy)(w,alpha,x,y);
687:   PetscLogEventEnd(VEC_WAXPY,x,y,w,0);
688:   PetscObjectStateIncrease((PetscObject)w);
689:   return(0);
690: }


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

698:    Not Collective

700:    Input Parameters:
701: +  x - vector to insert in
702: .  ni - number of elements to add
703: .  ix - indices where to add
704: .  y - array of values
705: -  iora - either INSERT_VALUES or ADD_VALUES, where
706:    ADD_VALUES adds values to any existing entries, and
707:    INSERT_VALUES replaces existing entries with new values

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

712:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
713:    options cannot be mixed without intervening calls to the assembly
714:    routines.

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

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

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

727:    Level: beginner

729:    Concepts: vector^setting values

731: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesLocal(),
732:            VecSetValue(), VecSetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecGetValues()
733: @*/
734: PetscErrorCode  VecSetValues(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
735: {

743:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
744:   (*x->ops->setvalues)(x,ni,ix,y,iora);
745:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
746:   PetscObjectStateIncrease((PetscObject)x);
747:   return(0);
748: }

752: /*@
753:    VecGetValues - Gets values from certain locations of a vector. Currently 
754:           can only get values on the same processor

756:     Collective on Vec
757:  
758:    Input Parameters:
759: +  x - vector to get values from
760: .  ni - number of elements to get
761: -  ix - indices where to get them from (in global 1d numbering)

763:    Output Parameter:
764: .   y - array of values

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

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

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

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

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

779:    Level: beginner

781:    Concepts: vector^getting values

783: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecGetValuesLocal(),
784:            VecGetValuesBlocked(), InsertMode, INSERT_VALUES, ADD_VALUES, VecSetValues()
785: @*/
786: PetscErrorCode  VecGetValues(Vec x,PetscInt ni,const PetscInt ix[],PetscScalar y[])
787: {

795:   (*x->ops->getvalues)(x,ni,ix,y);
796:   return(0);
797: }

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

804:    Not Collective

806:    Input Parameters:
807: +  x - vector to insert in
808: .  ni - number of blocks to add
809: .  ix - indices where to add in block count, rather than element count
810: .  y - array of values
811: -  iora - either INSERT_VALUES or ADD_VALUES, where
812:    ADD_VALUES adds values to any existing entries, and
813:    INSERT_VALUES replaces existing entries with new values

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

819:    Calls to VecSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES 
820:    options cannot be mixed without intervening calls to the assembly
821:    routines.

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

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

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

833:    Level: intermediate

835:    Concepts: vector^setting values blocked

837: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(),
838:            VecSetValues()
839: @*/
840: PetscErrorCode  VecSetValuesBlocked(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
841: {

849:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
850:   (*x->ops->setvaluesblocked)(x,ni,ix,y,iora);
851:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
852:   PetscObjectStateIncrease((PetscObject)x);
853:   return(0);
854: }


859: /*@
860:    VecSetValuesLocal - Inserts or adds values into certain locations of a vector,
861:    using a local ordering of the nodes. 

863:    Not Collective

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

874:    Level: intermediate

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

879:    Calls to VecSetValues() with the INSERT_VALUES and ADD_VALUES 
880:    options cannot be mixed without intervening calls to the assembly
881:    routines.

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

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

888:    Concepts: vector^setting values with local numbering

890: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetLocalToGlobalMapping(),
891:            VecSetValuesBlockedLocal()
892: @*/
893: PetscErrorCode  VecSetValuesLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
894: {
896:   PetscInt       lixp[128],*lix = lixp;


904:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
905:   if (!x->ops->setvalueslocal) {
906:     if (!x->mapping) {
907:       SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMapping()");
908:     }
909:     if (ni > 128) {
910:       PetscMalloc(ni*sizeof(PetscInt),&lix);
911:     }
912:     ISLocalToGlobalMappingApply(x->mapping,ni,(PetscInt*)ix,lix);
913:     (*x->ops->setvalues)(x,ni,lix,y,iora);
914:     if (ni > 128) {
915:       PetscFree(lix);
916:     }
917:   } else {
918:     (*x->ops->setvalueslocal)(x,ni,ix,y,iora);
919:   }
920:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
921:   PetscObjectStateIncrease((PetscObject)x);
922:   return(0);
923: }

927: /*@
928:    VecSetValuesBlockedLocal - Inserts or adds values into certain locations of a vector,
929:    using a local ordering of the nodes. 

931:    Not Collective

933:    Input Parameters:
934: +  x - vector to insert in
935: .  ni - number of blocks to add
936: .  ix - indices where to add in block count, not element count
937: .  y - array of values
938: -  iora - either INSERT_VALUES or ADD_VALUES, where
939:    ADD_VALUES adds values to any existing entries, and
940:    INSERT_VALUES replaces existing entries with new values

942:    Level: intermediate

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

948:    Calls to VecSetValuesBlockedLocal() with the INSERT_VALUES and ADD_VALUES 
949:    options cannot be mixed without intervening calls to the assembly
950:    routines.

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

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


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

960: .seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesBlocked(), 
961:            VecSetLocalToGlobalMappingBlock()
962: @*/
963: PetscErrorCode  VecSetValuesBlockedLocal(Vec x,PetscInt ni,const PetscInt ix[],const PetscScalar y[],InsertMode iora)
964: {
966:   PetscInt       lixp[128],*lix = lixp;

973:   if (!x->bmapping) {
974:     SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Local to global never set with VecSetLocalToGlobalMappingBlock()");
975:   }
976:   if (ni > 128) {
977:     PetscMalloc(ni*sizeof(PetscInt),&lix);
978:   }

980:   PetscLogEventBegin(VEC_SetValues,x,0,0,0);
981:   ISLocalToGlobalMappingApply(x->bmapping,ni,(PetscInt*)ix,lix);
982:   (*x->ops->setvaluesblocked)(x,ni,lix,y,iora);
983:   PetscLogEventEnd(VEC_SetValues,x,0,0,0);
984:   if (ni > 128) {
985:     PetscFree(lix);
986:   }
987:   PetscObjectStateIncrease((PetscObject)x);
988:   return(0);
989: }



995: /*@
996:    VecMTDot - Computes indefinite vector multiple dot products. 
997:    That is, it does NOT use the complex conjugate.

999:    Collective on Vec

1001:    Input Parameters:
1002: +  x - one vector
1003: .  nv - number of vectors
1004: -  y - array of vectors.  Note that vectors are pointers

1006:    Output Parameter:
1007: .  val - array of the dot products

1009:    Notes for Users of Complex Numbers:
1010:    For complex vectors, VecMTDot() computes the indefinite form
1011: $      val = (x,y) = y^T x,
1012:    where y^T denotes the transpose of y.

1014:    Use VecMDot() for the inner product
1015: $      val = (x,y) = y^H x,
1016:    where y^H denotes the conjugate transpose of y.

1018:    Level: intermediate

1020:    Concepts: inner product^multiple
1021:    Concepts: vector^multiple inner products

1023: .seealso: VecMDot(), VecTDot()
1024: @*/
1025: PetscErrorCode  VecMTDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1026: {


1039:   PetscLogEventBegin(VEC_MTDot,x,*y,0,0);
1040:   (*x->ops->mtdot)(x,nv,y,val);
1041:   PetscLogEventEnd(VEC_MTDot,x,*y,0,0);
1042:   return(0);
1043: }

1047: /*@
1048:    VecMDot - Computes vector multiple dot products. 

1050:    Collective on Vec

1052:    Input Parameters:
1053: +  x - one vector
1054: .  nv - number of vectors
1055: -  y - array of vectors. 

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

1060:    Notes for Users of Complex Numbers:
1061:    For complex vectors, VecMDot() computes 
1062: $     val = (x,y) = y^H x,
1063:    where y^H denotes the conjugate transpose of y.

1065:    Use VecMTDot() for the indefinite form
1066: $     val = (x,y) = y^T x,
1067:    where y^T denotes the transpose of y.

1069:    Level: intermediate

1071:    Concepts: inner product^multiple
1072:    Concepts: vector^multiple inner products

1074: .seealso: VecMTDot(), VecDot()
1075: @*/
1076: PetscErrorCode  VecMDot(Vec x,PetscInt nv,const Vec y[],PetscScalar val[])
1077: {

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

1092:   PetscLogEventBarrierBegin(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1093:   (*x->ops->mdot)(x,nv,y,val);
1094:   PetscLogEventBarrierEnd(VEC_MDotBarrier,x,*y,0,0,((PetscObject)x)->comm);
1095:   return(0);
1096: }

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

1103:    Collective on Vec

1105:    Input Parameters:
1106: +  nv - number of scalars and x-vectors
1107: .  alpha - array of scalars
1108: .  y - one vector
1109: -  x - array of vectors

1111:    Level: intermediate

1113:    Concepts: BLAS

1115: .seealso: VecAXPY(), VecWAXPY(), VecAYPX()
1116: @*/
1117: PetscErrorCode  VecMAXPY(Vec y,PetscInt nv,const PetscScalar alpha[],Vec x[])
1118: {

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

1133:   PetscLogEventBegin(VEC_MAXPY,*x,y,0,0);
1134:   (*y->ops->maxpy)(y,nv,alpha,x);
1135:   PetscLogEventEnd(VEC_MAXPY,*x,y,0,0);
1136:   PetscObjectStateIncrease((PetscObject)y);
1137:   return(0);
1138: }

1140: /*MC
1141:    VecGetArray - Returns a pointer to a contiguous array that contains this 
1142:    processor's portion of the vector data. For the standard PETSc
1143:    vectors, VecGetArray() returns a pointer to the local data array and
1144:    does not use any copies. If the underlying vector data is not stored
1145:    in a contiquous array this routine will copy the data to a contiquous
1146:    array and return a pointer to that. You MUST call VecRestoreArray() 
1147:    when you no longer need access to the array.

1149:    Synopsis:
1150:    PetscErrorCode VecGetArray(Vec x,PetscScalar *a[])

1152:    Not Collective

1154:    Input Parameter:
1155: .  x - the vector

1157:    Output Parameter:
1158: .  a - location to put pointer to the array

1160:    Fortran Note:
1161:    This routine is used differently from Fortran 77
1162: $    Vec         x
1163: $    PetscScalar x_array(1)
1164: $    PetscOffset i_x
1165: $    PetscErrorCode ierr
1166: $       call VecGetArray(x,x_array,i_x,ierr)
1167: $
1168: $   Access first local entry in vector with
1169: $      value = x_array(i_x + 1)
1170: $
1171: $      ...... other code
1172: $       call VecRestoreArray(x,x_array,i_x,ierr)
1173:    For Fortran 90 see VecGetArrayF90()

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

1178:    Level: beginner

1180:    Concepts: vector^accessing local values

1182: .seealso: VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(), VecGetArray2d()
1183: M*/
1186: PetscErrorCode VecGetArray_Private(Vec x,PetscScalar *a[])
1187: {

1194:   (*x->ops->getarray)(x,a);
1195:   return(0);
1196: }


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

1206:    Not Collective

1208:    Input Parameter:
1209: +  x - the vectors
1210: -  n - the number of vectors

1212:    Output Parameter:
1213: .  a - location to put pointer to the array

1215:    Fortran Note:
1216:    This routine is not supported in Fortran.

1218:    Level: intermediate

1220: .seealso: VecGetArray(), VecRestoreArrays()
1221: @*/
1222: PetscErrorCode  VecGetArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1223: {
1225:   PetscInt       i;
1226:   PetscScalar    **q;

1232:   if (n <= 0) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Must get at least one array n = %D",n);
1233:   PetscMalloc(n*sizeof(PetscScalar*),&q);
1234:   for (i=0; i<n; ++i) {
1235:     VecGetArray(x[i],&q[i]);
1236:   }
1237:   *a = q;
1238:   return(0);
1239: }

1243: /*@C
1244:    VecRestoreArrays - Restores a group of vectors after VecGetArrays()
1245:    has been called.

1247:    Not Collective

1249:    Input Parameters:
1250: +  x - the vector
1251: .  n - the number of vectors
1252: -  a - location of pointer to arrays obtained from VecGetArrays()

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

1260:    Fortran Note:
1261:    This routine is not supported in Fortran.

1263:    Level: intermediate

1265: .seealso: VecGetArrays(), VecRestoreArray()
1266: @*/
1267: PetscErrorCode  VecRestoreArrays(const Vec x[],PetscInt n,PetscScalar **a[])
1268: {
1270:   PetscInt       i;
1271:   PetscScalar    **q = *a;


1278:   for(i=0;i<n;++i) {
1279:     VecRestoreArray(x[i],&q[i]);
1280:  }
1281:   PetscFree(q);
1282:   return(0);
1283: }

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

1288:    Not Collective

1290:    Synopsis:
1291:    PetscErrorCode VecRestoreArray(Vec x,PetscScalar *a[])

1293:    Input Parameters:
1294: +  x - the vector
1295: -  a - location of pointer to array obtained from VecGetArray()

1297:    Level: beginner

1299:    Notes:
1300:    For regular PETSc vectors this routine does not involve any copies. For
1301:    any special vectors that do not store local vector data in a contiguous
1302:    array, this routine will copy the data back into the underlying 
1303:    vector data structure from the array obtained with VecGetArray().

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

1309:    Fortran Note:
1310:    This routine is used differently from Fortran 77
1311: $    Vec         x
1312: $    PetscScalar x_array(1)
1313: $    PetscOffset i_x
1314: $    PetscErrorCode ierr
1315: $       call VecGetArray(x,x_array,i_x,ierr)
1316: $
1317: $   Access first local entry in vector with
1318: $      value = x_array(i_x + 1)
1319: $
1320: $      ...... other code
1321: $       call VecRestoreArray(x,x_array,i_x,ierr)

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

1327: .seealso: VecGetArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(), VecRestoreArray2d()
1328: M*/
1331: PetscErrorCode VecRestoreArray_Private(Vec x,PetscScalar *a[])
1332: {

1339: #if defined(PETSC_USE_DEBUG)
1340:   CHKMEMQ;
1341: #endif
1342:   if (x->ops->restorearray) {
1343:     (*x->ops->restorearray)(x,a);
1344:   }
1345:   PetscObjectStateIncrease((PetscObject)x);
1346:   return(0);
1347: }


1352: /*@
1353:    VecPlaceArray - Allows one to replace the array in a vector with an
1354:    array provided by the user. This is useful to avoid copying an array
1355:    into a vector.

1357:    Not Collective

1359:    Input Parameters:
1360: +  vec - the vector
1361: -  array - the array

1363:    Notes:
1364:    You can return to the original array with a call to VecResetArray()

1366:    Level: developer

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

1370: @*/
1371: PetscErrorCode  VecPlaceArray(Vec vec,const PetscScalar array[])
1372: {

1379:   if (vec->ops->placearray) {
1380:     (*vec->ops->placearray)(vec,array);
1381:   } else {
1382:     SETERRQ(PETSC_ERR_SUP,"Cannot place array in this type of vector");
1383:   }
1384:   PetscObjectStateIncrease((PetscObject)vec);
1385:   return(0);
1386: }


1391: /*@C
1392:    VecReplaceArray - Allows one to replace the array in a vector with an
1393:    array provided by the user. This is useful to avoid copying an array
1394:    into a vector.

1396:    Not Collective

1398:    Input Parameters:
1399: +  vec - the vector
1400: -  array - the array

1402:    Notes:
1403:    This permanently replaces the array and frees the memory associated
1404:    with the old array.

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

1409:    Not supported from Fortran

1411:    Level: developer

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

1415: @*/
1416: PetscErrorCode  VecReplaceArray(Vec vec,const PetscScalar array[])
1417: {

1423:   if (vec->ops->replacearray) {
1424:     (*vec->ops->replacearray)(vec,array);
1425:  } else {
1426:     SETERRQ(PETSC_ERR_SUP,"Cannot replace array in this type of vector");
1427:   }
1428:   PetscObjectStateIncrease((PetscObject)vec);
1429:   return(0);
1430: }

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

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

1439:     Collective on Vec

1441:     Input Parameters:
1442: +   x - a vector to mimic
1443: -   n - the number of vectors to obtain

1445:     Output Parameters:
1446: +   y - Fortran90 pointer to the array of vectors
1447: -   ierr - error code

1449:     Example of Usage: 
1450: .vb
1451:     Vec x
1452:     Vec, pointer :: y(:)
1453:     ....
1454:     call VecDuplicateVecsF90(x,2,y,ierr)
1455:     call VecSet(y(2),alpha,ierr)
1456:     call VecSet(y(2),alpha,ierr)
1457:     ....
1458:     call VecDestroyVecsF90(y,2,ierr)
1459: .ve

1461:     Notes:
1462:     Not yet supported for all F90 compilers

1464:     Use VecDestroyVecsF90() to free the space.

1466:     Level: beginner

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

1470: M*/

1472: /*MC
1473:     VecRestoreArrayF90 - Restores a vector to a usable state after a call to
1474:     VecGetArrayF90().

1476:     Synopsis:
1477:     VecRestoreArrayF90(Vec x,{Scalar, pointer :: xx_v(:)},integer ierr)

1479:     Not collective

1481:     Input Parameters:
1482: +   x - vector
1483: -   xx_v - the Fortran90 pointer to the array

1485:     Output Parameter:
1486: .   ierr - error code

1488:     Example of Usage: 
1489: .vb
1490:     PetscScalar, pointer :: xx_v(:)
1491:     ....
1492:     call VecGetArrayF90(x,xx_v,ierr)
1493:     a = xx_v(3)
1494:     call VecRestoreArrayF90(x,xx_v,ierr)
1495: .ve
1496:    
1497:     Notes:
1498:     Not yet supported for all F90 compilers

1500:     Level: beginner

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

1504: M*/

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

1509:     Synopsis:
1510:     VecDestroyVecsF90({Vec, pointer :: x(:)},integer n,integer ierr)

1512:     Input Parameters:
1513: +   x - pointer to array of vector pointers
1514: -   n - the number of vectors previously obtained

1516:     Output Parameter:
1517: .   ierr - error code

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

1522:     Level: beginner

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

1526: M*/

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

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

1537:     Not Collective 

1539:     Input Parameter:
1540: .   x - vector

1542:     Output Parameters:
1543: +   xx_v - the Fortran90 pointer to the array
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

1555:     Notes:
1556:     Not yet supported for all F90 compilers

1558:     Level: beginner

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

1562: M*/


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

1572:    Not Collective

1574:    Input Parameter:
1575: +  x - the vector
1576: .  m - first dimension of two dimensional array
1577: .  n - second dimension of two dimensional array
1578: .  mstart - first index you will use in first coordinate direction (often 0)
1579: -  nstart - first index in the second coordinate direction (often 0)

1581:    Output Parameter:
1582: .  a - location to put pointer to the array

1584:    Level: developer

1586:   Notes:
1587:    For a vector obtained from DACreateLocalVector() mstart and nstart are likely
1588:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1589:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1590:    the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray2d().
1591:    
1592:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1596: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1597:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1598:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1599: @*/
1600: PetscErrorCode  VecGetArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1601: {
1603:   PetscInt       i,N;
1604:   PetscScalar    *aa;

1610:   VecGetLocalSize(x,&N);
1611:   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);
1612:   VecGetArray(x,&aa);

1614:   PetscMalloc(m*sizeof(PetscScalar*),a);
1615:   for (i=0; i<m; i++) (*a)[i] = aa + i*n - nstart;
1616:   *a -= mstart;
1617:   return(0);
1618: }

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

1625:    Not Collective

1627:    Input Parameters:
1628: +  x - the vector
1629: .  m - first dimension of two dimensional array
1630: .  n - second dimension of the two dimensional array
1631: .  mstart - first index you will use in first coordinate direction (often 0)
1632: .  nstart - first index in the second coordinate direction (often 0)
1633: -  a - location of pointer to array obtained from VecGetArray2d()

1635:    Level: developer

1637:    Notes:
1638:    For regular PETSc vectors this routine does not involve any copies. For
1639:    any special vectors that do not store local vector data in a contiguous
1640:    array, this routine will copy the data back into the underlying 
1641:    vector data structure from the array obtained with VecGetArray().

1643:    This routine actually zeros out the a pointer. 

1645: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1646:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1647:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1648: @*/
1649: PetscErrorCode  VecRestoreArray2d(Vec x,PetscInt m,PetscInt n,PetscInt mstart,PetscInt nstart,PetscScalar **a[])
1650: {
1652:   void           *dummy;

1658:   dummy = (void*)(*a + mstart);
1659:   PetscFree(dummy);
1660:   VecRestoreArray(x,PETSC_NULL);
1661:   return(0);
1662: }

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

1671:    Not Collective

1673:    Input Parameter:
1674: +  x - the vector
1675: .  m - first dimension of two dimensional array
1676: -  mstart - first index you will use in first coordinate direction (often 0)

1678:    Output Parameter:
1679: .  a - location to put pointer to the array

1681:    Level: developer

1683:   Notes:
1684:    For a vector obtained from DACreateLocalVector() mstart are likely
1685:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1686:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). 
1687:    
1688:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

1690: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1691:           VecRestoreArray2d(), DAVecGetArray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1692:           VecGetArray2d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1693: @*/
1694: PetscErrorCode  VecGetArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1695: {
1697:   PetscInt       N;

1703:   VecGetLocalSize(x,&N);
1704:   if (m != N) SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Local array size %D does not match 1d array dimensions %D",N,m);
1705:   VecGetArray(x,a);
1706:   *a  -= mstart;
1707:   return(0);
1708: }

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

1715:    Not Collective

1717:    Input Parameters:
1718: +  x - the vector
1719: .  m - first dimension of two dimensional array
1720: .  mstart - first index you will use in first coordinate direction (often 0)
1721: -  a - location of pointer to array obtained from VecGetArray21()

1723:    Level: developer

1725:    Notes:
1726:    For regular PETSc vectors this routine does not involve any copies. For
1727:    any special vectors that do not store local vector data in a contiguous
1728:    array, this routine will copy the data back into the underlying 
1729:    vector data structure from the array obtained with VecGetArray1d().

1731:    This routine actually zeros out the a pointer. 

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

1735: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1736:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1737:           VecGetArray1d(), VecRestoreArray2d(), VecGetArray4d(), VecRestoreArray4d()
1738: @*/
1739: PetscErrorCode  VecRestoreArray1d(Vec x,PetscInt m,PetscInt mstart,PetscScalar *a[])
1740: {

1746:   VecRestoreArray(x,PETSC_NULL);
1747:   return(0);
1748: }


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

1758:    Not Collective

1760:    Input Parameter:
1761: +  x - the vector
1762: .  m - first dimension of three dimensional array
1763: .  n - second dimension of three dimensional array
1764: .  p - third dimension of three dimensional array
1765: .  mstart - first index you will use in first coordinate direction (often 0)
1766: .  nstart - first index in the second coordinate direction (often 0)
1767: -  pstart - first index in the third coordinate direction (often 0)

1769:    Output Parameter:
1770: .  a - location to put pointer to the array

1772:    Level: developer

1774:   Notes:
1775:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1776:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1777:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1778:    the arguments from DAGet[Ghost]Corners() are reversed in the call to VecGetArray3d().
1779:    
1780:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1784: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1785:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1786:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1787: @*/
1788: PetscErrorCode  VecGetArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1789: {
1791:   PetscInt       i,N,j;
1792:   PetscScalar    *aa,**b;

1798:   VecGetLocalSize(x,&N);
1799:   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);
1800:   VecGetArray(x,&aa);

1802:   PetscMalloc(m*sizeof(PetscScalar**)+m*n*sizeof(PetscScalar*),a);
1803:   b    = (PetscScalar **)((*a) + m);
1804:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
1805:   for (i=0; i<m; i++) {
1806:     for (j=0; j<n; j++) {
1807:       b[i*n+j] = aa + i*n*p + j*p - pstart;
1808:     }
1809:   }
1810:   *a -= mstart;
1811:   return(0);
1812: }

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

1819:    Not Collective

1821:    Input Parameters:
1822: +  x - the vector
1823: .  m - first dimension of three dimensional array
1824: .  n - second dimension of the three dimensional array
1825: .  p - third dimension of the three dimensional array
1826: .  mstart - first index you will use in first coordinate direction (often 0)
1827: .  nstart - first index in the second coordinate direction (often 0)
1828: .  pstart - first index in the third coordinate direction (often 0)
1829: -  a - location of pointer to array obtained from VecGetArray3d()

1831:    Level: developer

1833:    Notes:
1834:    For regular PETSc vectors this routine does not involve any copies. For
1835:    any special vectors that do not store local vector data in a contiguous
1836:    array, this routine will copy the data back into the underlying 
1837:    vector data structure from the array obtained with VecGetArray().

1839:    This routine actually zeros out the a pointer. 

1841: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1842:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1843:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1844: @*/
1845: PetscErrorCode  VecRestoreArray3d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscScalar ***a[])
1846: {
1848:   void           *dummy;

1854:   dummy = (void*)(*a + mstart);
1855:   PetscFree(dummy);
1856:   VecRestoreArray(x,PETSC_NULL);
1857:   return(0);
1858: }

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

1867:    Not Collective

1869:    Input Parameter:
1870: +  x - the vector
1871: .  m - first dimension of four dimensional array
1872: .  n - second dimension of four dimensional array
1873: .  p - third dimension of four dimensional array
1874: .  q - fourth dimension of four dimensional array
1875: .  mstart - first index you will use in first coordinate direction (often 0)
1876: .  nstart - first index in the second coordinate direction (often 0)
1877: .  pstart - first index in the third coordinate direction (often 0)
1878: -  qstart - first index in the fourth coordinate direction (often 0)

1880:    Output Parameter:
1881: .  a - location to put pointer to the array

1883:    Level: beginner

1885:   Notes:
1886:    For a vector obtained from DACreateLocalVector() mstart, nstart, and pstart are likely
1887:    obtained from the corner indices obtained from DAGetGhostCorners() while for
1888:    DACreateGlobalVector() they are the corner indices from DAGetCorners(). In both cases
1889:    the arguments from DAGet[Ghost}Corners() are reversed in the call to VecGetArray3d().
1890:    
1891:    For standard PETSc vectors this is an inexpensive call; it does not copy the vector values.

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

1895: .seealso: VecGetArray(), VecRestoreArray(), VecGetArrays(), VecGetArrayF90(), VecPlaceArray(),
1896:           VecRestoreArray2d(), DAVecGetarray(), DAVecRestoreArray(), VecGetArray3d(), VecRestoreArray3d(),
1897:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d()
1898: @*/
1899: PetscErrorCode  VecGetArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1900: {
1902:   PetscInt       i,N,j,k;
1903:   PetscScalar    *aa,***b,**c;

1909:   VecGetLocalSize(x,&N);
1910:   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);
1911:   VecGetArray(x,&aa);

1913:   PetscMalloc(m*sizeof(PetscScalar***)+m*n*sizeof(PetscScalar**)+m*n*p*sizeof(PetscScalar*),a);
1914:   b    = (PetscScalar ***)((*a) + m);
1915:   c    = (PetscScalar **)(b + m*n);
1916:   for (i=0; i<m; i++)   (*a)[i] = b + i*n - nstart;
1917:   for (i=0; i<m; i++) {
1918:     for (j=0; j<n; j++) {
1919:       b[i*n+j] = c + i*n*p + j*p - pstart;
1920:     }
1921:   }
1922:   for (i=0; i<m; i++) {
1923:     for (j=0; j<n; j++) {
1924:       for (k=0; k<p; k++) {
1925:         c[i*n*p+j*p+k] = aa + i*n*p*q + j*p*q + k*q - qstart;
1926:       }
1927:     }
1928:   }
1929:   *a -= mstart;
1930:   return(0);
1931: }

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

1938:    Not Collective

1940:    Input Parameters:
1941: +  x - the vector
1942: .  m - first dimension of four dimensional array
1943: .  n - second dimension of the four dimensional array
1944: .  p - third dimension of the four dimensional array
1945: .  q - fourth dimension of the four dimensional array
1946: .  mstart - first index you will use in first coordinate direction (often 0)
1947: .  nstart - first index in the second coordinate direction (often 0)
1948: .  pstart - first index in the third coordinate direction (often 0)
1949: .  qstart - first index in the fourth coordinate direction (often 0)
1950: -  a - location of pointer to array obtained from VecGetArray4d()

1952:    Level: beginner

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

1960:    This routine actually zeros out the a pointer. 

1962: .seealso: VecGetArray(), VecRestoreArray(), VecRestoreArrays(), VecRestoreArrayF90(), VecPlaceArray(),
1963:           VecGetArray2d(), VecGetArray3d(), VecRestoreArray3d(), DAVecGetArray(), DAVecRestoreArray()
1964:           VecGetArray1d(), VecRestoreArray1d(), VecGetArray4d(), VecRestoreArray4d(), VecGet
1965: @*/
1966: PetscErrorCode  VecRestoreArray4d(Vec x,PetscInt m,PetscInt n,PetscInt p,PetscInt q,PetscInt mstart,PetscInt nstart,PetscInt pstart,PetscInt qstart,PetscScalar ****a[])
1967: {
1969:   void           *dummy;

1975:   dummy = (void*)(*a + mstart);
1976:   PetscFree(dummy);
1977:   VecRestoreArray(x,PETSC_NULL);
1978:   return(0);
1979: }