Actual source code: dagtol.c

  1: /*
  2:   Code for manipulating distributed regular arrays in parallel.
  3: */

 5:  #include src/dm/da/daimpl.h

  9: /*@
 10:    DAGlobalToLocalBegin - Maps values from the global vector to the local
 11:    patch; the ghost points are included. Must be followed by 
 12:    DAGlobalToLocalEnd() to complete the exchange.

 14:    Collective on DA

 16:    Input Parameters:
 17: +  da - the distributed array context
 18: .  g - the global vector
 19: -  mode - one of INSERT_VALUES or ADD_VALUES

 21:    Output Parameter:
 22: .  l  - the local values

 24:    Level: beginner

 26:    Notes:
 27:    The global and local vectors used here need not be the same as those
 28:    obtained from DACreateGlobalVector() and DACreateLocalVector(), BUT they
 29:    must have the same parallel data layout; they could, for example, be 
 30:    obtained with VecDuplicate() from the DA originating vectors.

 32: .keywords: distributed array, global to local, begin

 34: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
 35:           DALocalToLocalBegin(), DALocalToLocalEnd(),
 36:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
 37:           

 39: @*/
 40: PetscErrorCode DAGlobalToLocalBegin(DA da,Vec g,InsertMode mode,Vec l)
 41: {

 48:   VecScatterBegin(g,l,mode,SCATTER_FORWARD,da->gtol);
 49:   return(0);
 50: }

 54: /*@
 55:    DALocalToGlobalBegin - Adds values from the local (ghosted) vector
 56:    into the global (nonghosted) vector.

 58:    Collective on DA

 60:    Input Parameters:
 61: +  da - the distributed array context
 62: -  l  - the local values

 64:    Output Parameter:
 65: .  g - the global vector

 67:    Level: beginner

 69:    Notes:
 70:    Use DALocalToGlobal() to discard the ghost point values

 72:    The global and local vectors used here need not be the same as those
 73:    obtained from DACreateGlobalVector() and DACreateLocalVector(), BUT they
 74:    must have the same parallel data layout; they could, for example, be 
 75:    obtained with VecDuplicate() from the DA originating vectors.

 77: .keywords: distributed array, global to local, begin

 79: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
 80:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalEnd()

 82: @*/
 83: PetscErrorCode DALocalToGlobalBegin(DA da,Vec l,Vec g)
 84: {

 91:   VecScatterBegin(l,g,ADD_VALUES,SCATTER_REVERSE,da->gtol);
 92:   return(0);
 93: }

 97: /*@
 98:    DALocalToGlobalEnd - Adds values from the local (ghosted) vector
 99:    into the global (nonghosted) vector.

101:    Collective on DA

103:    Input Parameters:
104: +  da - the distributed array context
105: -  l  - the local values

107:    Output Parameter:
108: .  g - the global vector

110:    Level: beginner

112:    Notes:
113:    Use DALocalToGlobal() to discard the ghost point values

115:    The global and local vectors used here need not be the same as those
116:    obtained from DACreateGlobalVector() and DACreateLocalVector(), BUT they
117:    must have the same parallel data layout; they could, for example, be 
118:    obtained with VecDuplicate() from the DA originating vectors.

120: .keywords: distributed array, global to local, begin

122: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
123:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalBegin()

125: @*/
126: PetscErrorCode DALocalToGlobalEnd(DA da,Vec l,Vec g)
127: {

134:   VecScatterEnd(l,g,ADD_VALUES,SCATTER_REVERSE,da->gtol);
135:   return(0);
136: }

140: /*@
141:    DAGlobalToLocalEnd - Maps values from the global vector to the local
142:    patch; the ghost points are included. Must be preceeded by 
143:    DAGlobalToLocalBegin().

145:    Collective on DA

147:    Input Parameters:
148: +  da - the distributed array context
149: .  g - the global vector
150: -  mode - one of INSERT_VALUES or ADD_VALUES

152:    Output Parameter:
153: .  l  - the local values

155:    Level: beginner

157:    Notes:
158:    The global and local vectors used here need not be the same as those
159:    obtained from DACreateGlobalVector() and DACreateLocalVector(), BUT they
160:    must have the same parallel data layout; they could, for example, be 
161:    obtained with VecDuplicate() from the DA originating vectors.

163: .keywords: distributed array, global to local, end

165: .seealso: DAGlobalToLocalBegin(), DALocalToGlobal(), DACreate2d(),
166:      DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalBegin(), DALocalToGlobalEnd()
167: @*/
168: PetscErrorCode DAGlobalToLocalEnd(DA da,Vec g,InsertMode mode,Vec l)
169: {

176:   VecScatterEnd(g,l,mode,SCATTER_FORWARD,da->gtol);
177:   return(0);
178: }

180: EXTERN PetscErrorCode DAGetNatural_Private(DA,PetscInt*,IS*);
183: /*
184:    DAGlobalToNatural_Create - Create the global to natural scatter object

186:    Collective on DA

188:    Input Parameter:
189: .  da - the distributed array context

191:    Level: developer

193:    Notes: This is an internal routine called by DAGlobalToNatural() to 
194:      create the scatter context.

196: .keywords: distributed array, global to local, begin

198: .seealso: DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(), 
199:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector()
200: */
201: PetscErrorCode DAGlobalToNatural_Create(DA da)
202: {
204:   PetscInt  m,start,Nlocal;
205:   IS  from,to;
206:   Vec global;

210:   if (!da->natural) {
211:     SETERRQ(PETSC_ERR_ORDER,"Natural layout vector not yet created; cannot scatter into it");
212:   }

214:   /* create the scatter context */
215:   VecGetLocalSize(da->natural,&m);
216:   VecGetOwnershipRange(da->natural,&start,PETSC_NULL);

218:   DAGetNatural_Private(da,&Nlocal,&to);
219:   if (Nlocal != m) SETERRQ2(PETSC_ERR_PLIB,"Internal error: Nlocal %D local vector size %D",Nlocal,m);
220:   ISCreateStride(da->comm,m,start,1,&from);
221:   VecCreateMPIWithArray(da->comm,da->Nlocal,PETSC_DETERMINE,0,&global);
222:   VecScatterCreate(global,from,da->natural,to,&da->gton);
223:   VecDestroy(global);
224:   ISDestroy(from);
225:   ISDestroy(to);
226:   return(0);
227: }

231: /*@
232:    DAGlobalToNaturalBegin - Maps values from the global vector to a global vector
233:    in the "natural" grid ordering. Must be followed by 
234:    DAGlobalToNaturalEnd() to complete the exchange.

236:    Collective on DA

238:    Input Parameters:
239: +  da - the distributed array context
240: .  g - the global vector
241: -  mode - one of INSERT_VALUES or ADD_VALUES

243:    Output Parameter:
244: .  l  - the natural ordering values

246:    Level: advanced

248:    Notes:
249:    The global and natrual vectors used here need not be the same as those
250:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
251:    must have the same parallel data layout; they could, for example, be 
252:    obtained with VecDuplicate() from the DA originating vectors.

254: .keywords: distributed array, global to local, begin

256: .seealso: DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(), 
257:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
258:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
259: @*/
260: PetscErrorCode DAGlobalToNaturalBegin(DA da,Vec g,InsertMode mode,Vec l)
261: {

268:   if (!da->gton) {
269:     /* create the scatter context */
270:     DAGlobalToNatural_Create(da);
271:   }
272:   VecScatterBegin(g,l,mode,SCATTER_FORWARD,da->gton);
273:   return(0);
274: }

278: /*@
279:    DAGlobalToNaturalEnd - Maps values from the global vector to a global vector
280:    in the natural ordering. Must be preceeded by DAGlobalToNaturalBegin().

282:    Collective on DA

284:    Input Parameters:
285: +  da - the distributed array context
286: .  g - the global vector
287: -  mode - one of INSERT_VALUES or ADD_VALUES

289:    Output Parameter:
290: .  l  - the global values in the natural ordering

292:    Level: advanced

294:    Notes:
295:    The global and local vectors used here need not be the same as those
296:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
297:    must have the same parallel data layout; they could, for example, be 
298:    obtained with VecDuplicate() from the DA originating vectors.

300: .keywords: distributed array, global to local, end

302: .seealso: DAGlobalToNaturalBegin(), DALocalToGlobal(), DACreate2d(),
303:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
304:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
305: @*/
306: PetscErrorCode DAGlobalToNaturalEnd(DA da,Vec g,InsertMode mode,Vec l)
307: {

314:   VecScatterEnd(g,l,mode,SCATTER_FORWARD,da->gton);
315:   return(0);
316: }

320: /*@
321:    DANaturalToGlobalBegin - Maps values from a global vector in the "natural" ordering 
322:    to a global vector in the PETSc DA grid ordering. Must be followed by 
323:    DANaturalToGlobalEnd() to complete the exchange.

325:    Collective on DA

327:    Input Parameters:
328: +  da - the distributed array context
329: .  g - the global vector in a natural ordering
330: -  mode - one of INSERT_VALUES or ADD_VALUES

332:    Output Parameter:
333: .  l  - the values in the DA ordering

335:    Level: advanced

337:    Notes:
338:    The global and natural vectors used here need not be the same as those
339:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
340:    must have the same parallel data layout; they could, for example, be 
341:    obtained with VecDuplicate() from the DA originating vectors.

343: .keywords: distributed array, global to local, begin

345: .seealso: DAGlobalToNaturalEnd(), DAGlobalToNaturalBegin(), DALocalToGlobal(), DACreate2d(), 
346:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
347:           DALocalToGlobalBegin(), DALocalToGlobalEnd()

349: @*/
350: PetscErrorCode DANaturalToGlobalBegin(DA da,Vec g,InsertMode mode,Vec l)
351: {

358:   if (!da->gton) {
359:     /* create the scatter context */
360:     DAGlobalToNatural_Create(da);
361:   }
362:   VecScatterBegin(g,l,mode,SCATTER_REVERSE,da->gton);
363:   return(0);
364: }

368: /*@
369:    DANaturalToGlobalEnd - Maps values from the natural ordering global vector 
370:    to a global vector in the PETSc DA ordering. Must be preceeded by DANaturalToGlobalBegin().

372:    Collective on DA

374:    Input Parameters:
375: +  da - the distributed array context
376: .  g - the global vector in a natural ordering
377: -  mode - one of INSERT_VALUES or ADD_VALUES

379:    Output Parameter:
380: .  l  - the global values in the PETSc DA ordering

382:    Level: intermediate

384:    Notes:
385:    The global and local vectors used here need not be the same as those
386:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
387:    must have the same parallel data layout; they could, for example, be 
388:    obtained with VecDuplicate() from the DA originating vectors.

390: .keywords: distributed array, global to local, end

392: .seealso: DAGlobalToNaturalBegin(), DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(),
393:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
394:           DALocalToGlobalBegin(), DALocalToGlobalEnd()

396: @*/
397: PetscErrorCode DANaturalToGlobalEnd(DA da,Vec g,InsertMode mode,Vec l)
398: {

405:   VecScatterEnd(g,l,mode,SCATTER_REVERSE,da->gton);
406:   return(0);
407: }