Actual source code: dagetarray.c

petsc-3.6.1 2015-07-22
Report Typos and Errors
  2: #include <petsc/private/dmdaimpl.h>    /*I   "petscdmda.h"   I*/

  6: /*@C
  7:    DMDAVecGetArray - Returns a multiple dimension array that shares data with
  8:       the underlying vector and is indexed using the global dimensions.

 10:    Logically collective on Vec

 12:    Input Parameter:
 13: +  da - the distributed array
 14: -  vec - the vector, either a vector the same size as one obtained with DMCreateGlobalVector() or DMCreateLocalVector()

 16:    Output Parameter:
 17: .  array - the array

 19:    Notes:
 20:     Call DMDAVecRestoreArray() once you have finished accessing the vector entries.

 22:     In C, the indexing is "backwards" from what expects: array[k][j][i] NOT array[i][j][k]!

 24:     If vec is a local vector (obtained with DMCreateLocalVector() etc) then the ghost point locations are accessible. If it is
 25:     a global vector then the ghost points are not accessible. Of course with the local vector you will have had to do the

 27:     appropriate DMGlobalToLocalBegin() and DMGlobalToLocalEnd() to have correct values in the ghost locations.

 29:   Fortran Notes: From Fortran use DMDAVecGetArrayF90() and pass for the array type PetscScalar,pointer :: array(:,...,:) of the appropriate
 30:        dimension. For a DMDA created with a dof of 1 use the dimension of the DMDA, for a DMDA created with a dof greater than 1 use one more than the
 31:        dimension of the DMDA. The order of the indices is array(xs:xs+xm-1,ys:ys+ym-1,zs:zs+zm-1) (when dof is 1) otherwise
 32:        array(0:dof-1,xs:xs+xm-1,ys:ys+ym-1,zs:zs+zm-1) where the values are obtained from
 33:        DMDAGetCorners() for a global array or DMDAGetGhostCorners() for a local array. Include petsc/finclude/petscdmda.h90 to access this routine.

 35:   Due to bugs in the compiler DMDAVecGetArrayF90() does not work with gfortran versions before 4.5

 37:   Level: intermediate

 39: .keywords: distributed array, get, corners, nodes, local indices, coordinates

 41: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecRestoreArray(), DMDAVecRestoreArrayDOF()
 42:           DMDAVecGetArrayDOF()
 43: @*/
 44: PetscErrorCode  DMDAVecGetArray(DM da,Vec vec,void *array)
 45: {
 47:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

 53:   if (da->defaultSection) {
 54:     VecGetArray(vec,(PetscScalar**)array);
 55:     return(0);
 56:   }
 57:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
 58:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
 59:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

 61:   /* Handle case where user passes in global vector as opposed to local */
 62:   VecGetLocalSize(vec,&N);
 63:   if (N == xm*ym*zm*dof) {
 64:     gxm = xm;
 65:     gym = ym;
 66:     gzm = zm;
 67:     gxs = xs;
 68:     gys = ys;
 69:     gzs = zs;
 70:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

 72:   if (dim == 1) {
 73:     VecGetArray1d(vec,gxm*dof,gxs*dof,(PetscScalar**)array);
 74:   } else if (dim == 2) {
 75:     VecGetArray2d(vec,gym,gxm*dof,gys,gxs*dof,(PetscScalar***)array);
 76:   } else if (dim == 3) {
 77:     VecGetArray3d(vec,gzm,gym,gxm*dof,gzs,gys,gxs*dof,(PetscScalar****)array);
 78:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
 79:   return(0);
 80: }

 84: /*@
 85:    DMDAVecRestoreArray - Restores a multiple dimension array obtained with DMDAVecGetArray()

 87:    Logically collective on Vec

 89:    Input Parameter:
 90: +  da - the distributed array
 91: .  vec - the vector, either a vector the same size as one obtained with
 92:          DMCreateGlobalVector() or DMCreateLocalVector()
 93: -  array - the array, non-NULL pointer is zeroed

 95:   Level: intermediate

 97:   Fortran Notes: From Fortran use DMDAVecRestoreArrayF90()

 99: .keywords: distributed array, get, corners, nodes, local indices, coordinates

101: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecGetArray()
102: @*/
103: PetscErrorCode  DMDAVecRestoreArray(DM da,Vec vec,void *array)
104: {
106:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

112:   if (da->defaultSection) {
113:     VecRestoreArray(vec,(PetscScalar**)array);
114:     return(0);
115:   }
116:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
117:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
118:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

120:   /* Handle case where user passes in global vector as opposed to local */
121:   VecGetLocalSize(vec,&N);
122:   if (N == xm*ym*zm*dof) {
123:     gxm = xm;
124:     gym = ym;
125:     gzm = zm;
126:     gxs = xs;
127:     gys = ys;
128:     gzs = zs;
129:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

131:   if (dim == 1) {
132:     VecRestoreArray1d(vec,gxm*dof,gxs*dof,(PetscScalar**)array);
133:   } else if (dim == 2) {
134:     VecRestoreArray2d(vec,gym,gxm*dof,gys,gxs*dof,(PetscScalar***)array);
135:   } else if (dim == 3) {
136:     VecRestoreArray3d(vec,gzm,gym,gxm*dof,gzs,gys,gxs*dof,(PetscScalar****)array);
137:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
138:   return(0);
139: }

143: /*@C
144:    DMDAVecGetArrayDOF - Returns a multiple dimension array that shares data with
145:       the underlying vector and is indexed using the global dimensions.

147:    Logically collective

149:    Input Parameter:
150: +  da - the distributed array
151: -  vec - the vector, either a vector the same size as one obtained with
152:          DMCreateGlobalVector() or DMCreateLocalVector()

154:    Output Parameter:
155: .  array - the array

157:    Notes:
158:     Call DMDAVecRestoreArrayDOF() once you have finished accessing the vector entries.

160:     In C, the indexing is "backwards" from what expects: array[k][j][i][DOF] NOT array[i][j][k][DOF]!

162:     In Fortran 90 you do not need a version of DMDAVecRestoreArrayDOF() just use  DMDAVecRestoreArrayF90() and declare your array with one higher dimension,
163:     see src/dm/examples/tutorials/ex11f90.F

165:   Level: intermediate

167: .keywords: distributed array, get, corners, nodes, local indices, coordinates

169: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecRestoreArray(), DMDAVecGetArray(), DMDAVecRestoreArrayDOF()
170: @*/
171: PetscErrorCode  DMDAVecGetArrayDOF(DM da,Vec vec,void *array)
172: {
174:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

177:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
178:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
179:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

181:   /* Handle case where user passes in global vector as opposed to local */
182:   VecGetLocalSize(vec,&N);
183:   if (N == xm*ym*zm*dof) {
184:     gxm = xm;
185:     gym = ym;
186:     gzm = zm;
187:     gxs = xs;
188:     gys = ys;
189:     gzs = zs;
190:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

192:   if (dim == 1) {
193:     VecGetArray2d(vec,gxm,dof,gxs,0,(PetscScalar***)array);
194:   } else if (dim == 2) {
195:     VecGetArray3d(vec,gym,gxm,dof,gys,gxs,0,(PetscScalar****)array);
196:   } else if (dim == 3) {
197:     VecGetArray4d(vec,gzm,gym,gxm,dof,gzs,gys,gxs,0,(PetscScalar*****)array);
198:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
199:   return(0);
200: }

204: /*@
205:    DMDAVecRestoreArrayDOF - Restores a multiple dimension array obtained with DMDAVecGetArrayDOF()

207:    Logically collective

209:    Input Parameter:
210: +  da - the distributed array
211: .  vec - the vector, either a vector the same size as one obtained with
212:          DMCreateGlobalVector() or DMCreateLocalVector()
213: -  array - the array

215:   Level: intermediate

217: .keywords: distributed array, get, corners, nodes, local indices, coordinates

219: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecGetArray(), DMDAVecGetArrayDOF(), DMDAVecRestoreArrayDOF()
220: @*/
221: PetscErrorCode  DMDAVecRestoreArrayDOF(DM da,Vec vec,void *array)
222: {
224:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

227:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
228:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
229:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

231:   /* Handle case where user passes in global vector as opposed to local */
232:   VecGetLocalSize(vec,&N);
233:   if (N == xm*ym*zm*dof) {
234:     gxm = xm;
235:     gym = ym;
236:     gzm = zm;
237:     gxs = xs;
238:     gys = ys;
239:     gzs = zs;
240:   }

242:   if (dim == 1) {
243:     VecRestoreArray2d(vec,gxm,dof,gxs,0,(PetscScalar***)array);
244:   } else if (dim == 2) {
245:     VecRestoreArray3d(vec,gym,gxm,dof,gys,gxs,0,(PetscScalar****)array);
246:   } else if (dim == 3) {
247:     VecRestoreArray4d(vec,gzm,gym,gxm,dof,gzs,gys,gxs,0,(PetscScalar*****)array);
248:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
249:   return(0);
250: }

254: /*@C
255:    DMDAVecGetArrayRead - Returns a multiple dimension array that shares data with
256:       the underlying vector and is indexed using the global dimensions.

258:    Not collective

260:    Input Parameter:
261: +  da - the distributed array
262: -  vec - the vector, either a vector the same size as one obtained with DMCreateGlobalVector() or DMCreateLocalVector()

264:    Output Parameter:
265: .  array - the array

267:    Notes:
268:     Call DMDAVecRestoreArrayRead() once you have finished accessing the vector entries.

270:     In C, the indexing is "backwards" from what expects: array[k][j][i] NOT array[i][j][k]!

272:     If vec is a local vector (obtained with DMCreateLocalVector() etc) then the ghost point locations are accessible. If it is
273:     a global vector then the ghost points are not accessible. Of course with the local vector you will have had to do the

275:     appropriate DMGlobalToLocalBegin() and DMGlobalToLocalEnd() to have correct values in the ghost locations.

277:   Fortran Notes: From Fortran use DMDAVecGetArrayReadF90() and pass for the array type PetscScalar,pointer :: array(:,...,:) of the appropriate
278:        dimension. For a DMDA created with a dof of 1 use the dimension of the DMDA, for a DMDA created with a dof greater than 1 use one more than the
279:        dimension of the DMDA. The order of the indices is array(xs:xs+xm-1,ys:ys+ym-1,zs:zs+zm-1) (when dof is 1) otherwise
280:        array(0:dof-1,xs:xs+xm-1,ys:ys+ym-1,zs:zs+zm-1) where the values are obtained from
281:        DMDAGetCorners() for a global array or DMDAGetGhostCorners() for a local array. Include petsc/finclude/petscdmda.h90 to access this routine.

283:   Due to bugs in the compiler DMDAVecGetArrayReadF90() does not work with gfortran versions before 4.5

285:   Level: intermediate

287: .keywords: distributed array, get, corners, nodes, local indices, coordinates

289: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecRestoreArray(), DMDAVecRestoreArrayDOF()
290:           DMDAVecGetArrayDOF()
291: @*/
292: PetscErrorCode  DMDAVecGetArrayRead(DM da,Vec vec,void *array)
293: {
295:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

301:   if (da->defaultSection) {
302:     VecGetArrayRead(vec,(const PetscScalar**)array);
303:     return(0);
304:   }
305:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
306:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
307:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

309:   /* Handle case where user passes in global vector as opposed to local */
310:   VecGetLocalSize(vec,&N);
311:   if (N == xm*ym*zm*dof) {
312:     gxm = xm;
313:     gym = ym;
314:     gzm = zm;
315:     gxs = xs;
316:     gys = ys;
317:     gzs = zs;
318:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

320:   if (dim == 1) {
321:     VecGetArray1dRead(vec,gxm*dof,gxs*dof,(PetscScalar**)array);
322:   } else if (dim == 2) {
323:     VecGetArray2dRead(vec,gym,gxm*dof,gys,gxs*dof,(PetscScalar***)array);
324:   } else if (dim == 3) {
325:     VecGetArray3dRead(vec,gzm,gym,gxm*dof,gzs,gys,gxs*dof,(PetscScalar****)array);
326:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
327:   return(0);
328: }

332: /*@
333:    DMDAVecRestoreArrayRead - Restores a multiple dimension array obtained with DMDAVecGetArrayRead()

335:    Not collective

337:    Input Parameter:
338: +  da - the distributed array
339: .  vec - the vector, either a vector the same size as one obtained with
340:          DMCreateGlobalVector() or DMCreateLocalVector()
341: -  array - the array, non-NULL pointer is zeroed

343:   Level: intermediate

345:   Fortran Notes: From Fortran use DMDAVecRestoreArrayReadF90()

347: .keywords: distributed array, get, corners, nodes, local indices, coordinates

349: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecGetArray()
350: @*/
351: PetscErrorCode  DMDAVecRestoreArrayRead(DM da,Vec vec,void *array)
352: {
354:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

360:   if (da->defaultSection) {
361:     VecRestoreArrayRead(vec,(const PetscScalar**)array);
362:     return(0);
363:   }
364:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
365:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
366:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

368:   /* Handle case where user passes in global vector as opposed to local */
369:   VecGetLocalSize(vec,&N);
370:   if (N == xm*ym*zm*dof) {
371:     gxm = xm;
372:     gym = ym;
373:     gzm = zm;
374:     gxs = xs;
375:     gys = ys;
376:     gzs = zs;
377:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

379:   if (dim == 1) {
380:     VecRestoreArray1dRead(vec,gxm*dof,gxs*dof,(PetscScalar**)array);
381:   } else if (dim == 2) {
382:     VecRestoreArray2dRead(vec,gym,gxm*dof,gys,gxs*dof,(PetscScalar***)array);
383:   } else if (dim == 3) {
384:     VecRestoreArray3dRead(vec,gzm,gym,gxm*dof,gzs,gys,gxs*dof,(PetscScalar****)array);
385:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
386:   return(0);
387: }

391: /*@C
392:    DMDAVecGetArrayDOFRead - Returns a multiple dimension array that shares data with
393:       the underlying vector and is indexed using the global dimensions.

395:    Not Collective

397:    Input Parameter:
398: +  da - the distributed array
399: -  vec - the vector, either a vector the same size as one obtained with
400:          DMCreateGlobalVector() or DMCreateLocalVector()

402:    Output Parameter:
403: .  array - the array

405:    Notes:
406:     Call DMDAVecRestoreArrayDOFRead() once you have finished accessing the vector entries.

408:     In C, the indexing is "backwards" from what expects: array[k][j][i][DOF] NOT array[i][j][k][DOF]!

410:     In Fortran 90 you do not need a version of DMDAVecRestoreArrayDOF() just use  DMDAVecRestoreArrayReadF90() and declare your array with one higher dimension,
411:     see src/dm/examples/tutorials/ex11f90.F

413:   Level: intermediate

415: .keywords: distributed array, get, corners, nodes, local indices, coordinates

417: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecRestoreArray(), DMDAVecGetArray(), DMDAVecRestoreArrayDOF()
418: @*/
419: PetscErrorCode  DMDAVecGetArrayDOFRead(DM da,Vec vec,void *array)
420: {
422:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

425:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
426:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
427:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

429:   /* Handle case where user passes in global vector as opposed to local */
430:   VecGetLocalSize(vec,&N);
431:   if (N == xm*ym*zm*dof) {
432:     gxm = xm;
433:     gym = ym;
434:     gzm = zm;
435:     gxs = xs;
436:     gys = ys;
437:     gzs = zs;
438:   } else if (N != gxm*gym*gzm*dof) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Vector local size %D is not compatible with DMDA local sizes %D %D\n",N,xm*ym*zm*dof,gxm*gym*gzm*dof);

440:   if (dim == 1) {
441:     VecGetArray2dRead(vec,gxm,dof,gxs,0,(PetscScalar***)array);
442:   } else if (dim == 2) {
443:     VecGetArray3dRead(vec,gym,gxm,dof,gys,gxs,0,(PetscScalar****)array);
444:   } else if (dim == 3) {
445:     VecGetArray4dRead(vec,gzm,gym,gxm,dof,gzs,gys,gxs,0,(PetscScalar*****)array);
446:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
447:   return(0);
448: }

452: /*@
453:    DMDAVecRestoreArrayDOFRead - Restores a multiple dimension array obtained with DMDAVecGetArrayDOFRead()

455:    Not Collective

457:    Input Parameter:
458: +  da - the distributed array
459: .  vec - the vector, either a vector the same size as one obtained with
460:          DMCreateGlobalVector() or DMCreateLocalVector()
461: -  array - the array

463:   Level: intermediate

465: .keywords: distributed array, get, corners, nodes, local indices, coordinates

467: .seealso: DMDAGetGhostCorners(), DMDAGetCorners(), VecGetArray(), VecRestoreArray(), DMDAVecGetArray(), DMDAVecGetArrayDOF(), DMDAVecRestoreArrayDOF()
468: @*/
469: PetscErrorCode  DMDAVecRestoreArrayDOFRead(DM da,Vec vec,void *array)
470: {
472:   PetscInt       xs,ys,zs,xm,ym,zm,gxs,gys,gzs,gxm,gym,gzm,N,dim,dof;

475:   DMDAGetCorners(da,&xs,&ys,&zs,&xm,&ym,&zm);
476:   DMDAGetGhostCorners(da,&gxs,&gys,&gzs,&gxm,&gym,&gzm);
477:   DMDAGetInfo(da,&dim,0,0,0,0,0,0,&dof,0,0,0,0,0);

479:   /* Handle case where user passes in global vector as opposed to local */
480:   VecGetLocalSize(vec,&N);
481:   if (N == xm*ym*zm*dof) {
482:     gxm = xm;
483:     gym = ym;
484:     gzm = zm;
485:     gxs = xs;
486:     gys = ys;
487:     gzs = zs;
488:   }

490:   if (dim == 1) {
491:     VecRestoreArray2dRead(vec,gxm,dof,gxs,0,(PetscScalar***)array);
492:   } else if (dim == 2) {
493:     VecRestoreArray3dRead(vec,gym,gxm,dof,gys,gxs,0,(PetscScalar****)array);
494:   } else if (dim == 3) {
495:     VecRestoreArray4dRead(vec,gzm,gym,gxm,dof,gzs,gys,gxs,0,(PetscScalar*****)array);
496:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_CORRUPT,"DMDA dimension not 1, 2, or 3, it is %D\n",dim);
497:   return(0);
498: }