Actual source code: dagtol.c

  1: /*$Id: dagtol.c,v 1.29 2001/03/23 23:25:00 balay Exp $*/
  2: 
  3: /*
  4:   Code for manipulating distributed regular arrays in parallel.
  5: */

 7:  #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: int DAGlobalToLocalBegin(DA da,Vec g,InsertMode mode,Vec l)
 41: {

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

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

 56:    Collective on DA

 58:    Input Parameters:
 59: +  da - the distributed array context
 60: -  l  - the local values

 62:    Output Parameter:
 63: .  g - the global vector

 65:    Level: beginner

 67:    Notes:
 68:    Use DALocalToGlobal() to discard the ghost point values

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

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

 77: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
 78:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalEnd()

 80: @*/
 81: int DALocalToGlobalBegin(DA da,Vec l,Vec g)
 82: {

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

 93: /*@
 94:    DALocalToGlobalEnd - Adds values from the local (ghosted) vector
 95:    into the global (nonghosted) vector.

 97:    Collective on DA

 99:    Input Parameters:
100: +  da - the distributed array context
101: -  l  - the local values

103:    Output Parameter:
104: .  g - the global vector

106:    Level: beginner

108:    Notes:
109:    Use DALocalToGlobal() to discard the ghost point values

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

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

118: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
119:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalBegin()

121: @*/
122: int DALocalToGlobalEnd(DA da,Vec l,Vec g)
123: {

130:   VecScatterEnd(l,g,ADD_VALUES,SCATTER_REVERSE,da->gtol);
131:   return(0);
132: }

134: /*@
135:    DAGlobalToLocalEnd - Maps values from the global vector to the local
136:    patch; the ghost points are included. Must be preceeded by 
137:    DAGlobalToLocalBegin().

139:    Collective on DA

141:    Input Parameters:
142: +  da - the distributed array context
143: .  g - the global vector
144: -  mode - one of INSERT_VALUES or ADD_VALUES

146:    Output Parameter:
147: .  l  - the local values

149:    Level: beginner

151:    Notes:
152:    The global and local vectors used here need not be the same as those
153:    obtained from DACreateGlobalVector() and DACreateLocalVector(), BUT they
154:    must have the same parallel data layout; they could, for example, be 
155:    obtained with VecDuplicate() from the DA originating vectors.

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

159: .seealso: DAGlobalToLocalBegin(), DALocalToGlobal(), DACreate2d(),
160:      DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalBegin(), DALocalToGlobalEnd()
161: @*/
162: int DAGlobalToLocalEnd(DA da,Vec g,InsertMode mode,Vec l)
163: {

170:   VecScatterEnd(g,l,mode,SCATTER_FORWARD,da->gtol);
171:   return(0);
172: }

174: /*
175:    DAGlobalToNatural_Create - Create the global to natural scatter object

177:    Collective on DA

179:    Input Parameter:
180: .  da - the distributed array context

182:    Level: developer

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

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

189: .seealso: DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(), 
190:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector()
191: */
192: int DAGlobalToNatural_Create(DA da)
193: {
194:   int ierr,m,start;
195:   IS  from,to;

199:   if (!da->natural) {
200:     SETERRQ(1,"Natural layout vector not yet created; cannot scatter into it");
201:   }
202:   if (!da->ao) {
203:     SETERRQ(1,"Cannot use -da_noao with this function");
204:   }

206:   /* create the scatter context */
207:   VecGetLocalSize(da->natural,&m);
208:   VecGetOwnershipRange(da->natural,&start,PETSC_NULL);
209:   ISCreateStride(da->comm,m,start,1,&to);
210:   AOPetscToApplicationIS(da->ao,to);
211:   ISCreateStride(da->comm,m,start,1,&from);
212:   VecScatterCreate(da->global,from,da->natural,to,&da->gton);
213:   ISDestroy(from);
214:   ISDestroy(to);
215:   return(0);
216: }

218: /*@
219:    DAGlobalToNaturalBegin - Maps values from the global vector to a global vector
220:    in the "natural" grid ordering. Must be followed by 
221:    DAGlobalToNaturalEnd() to complete the exchange.

223:    Collective on DA

225:    Input Parameters:
226: +  da - the distributed array context
227: .  g - the global vector
228: -  mode - one of INSERT_VALUES or ADD_VALUES

230:    Output Parameter:
231: .  l  - the natural ordering values

233:    Level: advanced

235:    Notes:
236:    The global and natrual vectors used here need not be the same as those
237:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
238:    must have the same parallel data layout; they could, for example, be 
239:    obtained with VecDuplicate() from the DA originating vectors.

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

243: .seealso: DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(), 
244:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
245:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
246: @*/
247: int DAGlobalToNaturalBegin(DA da,Vec g,InsertMode mode,Vec l)
248: {

255:   if (!da->gton) {
256:     /* create the scatter context */
257:     DAGlobalToNatural_Create(da);
258:   }
259:   VecScatterBegin(g,l,mode,SCATTER_FORWARD,da->gton);
260:   return(0);
261: }

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

267:    Collective on DA

269:    Input Parameters:
270: +  da - the distributed array context
271: .  g - the global vector
272: -  mode - one of INSERT_VALUES or ADD_VALUES

274:    Output Parameter:
275: .  l  - the global values in the natural ordering

277:    Level: advanced

279:    Notes:
280:    The global and local vectors used here need not be the same as those
281:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
282:    must have the same parallel data layout; they could, for example, be 
283:    obtained with VecDuplicate() from the DA originating vectors.

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

287: .seealso: DAGlobalToNaturalBegin(), DALocalToGlobal(), DACreate2d(),
288:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
289:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
290: @*/
291: int DAGlobalToNaturalEnd(DA da,Vec g,InsertMode mode,Vec l)
292: {

299:   VecScatterEnd(g,l,mode,SCATTER_FORWARD,da->gton);
300:   return(0);
301: }

303: /*@
304:    DANaturalToGlobalBegin - Maps values from a global vector in the "natural" ordering 
305:    to a global vector in the PETSc DA grid ordering. Must be followed by 
306:    DANaturalToGlobalEnd() to complete the exchange.

308:    Collective on DA

310:    Input Parameters:
311: +  da - the distributed array context
312: .  g - the global vector in a natural ordering
313: -  mode - one of INSERT_VALUES or ADD_VALUES

315:    Output Parameter:
316: .  l  - the values in the DA ordering

318:    Level: advanced

320:    Notes:
321:    The global and natural vectors used here need not be the same as those
322:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
323:    must have the same parallel data layout; they could, for example, be 
324:    obtained with VecDuplicate() from the DA originating vectors.

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

328: .seealso: DAGlobalToNaturalEnd(), DAGlobalToNaturalBegin(), DALocalToGlobal(), DACreate2d(), 
329:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
330:           DALocalToGlobalBegin(), DALocalToGlobalEnd()

332: @*/
333: int DANaturalToGlobalBegin(DA da,Vec g,InsertMode mode,Vec l)
334: {

341:   if (!da->gton) {
342:     /* create the scatter context */
343:     DAGlobalToNatural_Create(da);
344:   }
345:   VecScatterBegin(g,l,mode,SCATTER_REVERSE,da->gton);
346:   return(0);
347: }

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

353:    Collective on DA

355:    Input Parameters:
356: +  da - the distributed array context
357: .  g - the global vector in a natural ordering
358: -  mode - one of INSERT_VALUES or ADD_VALUES

360:    Output Parameter:
361: .  l  - the global values in the PETSc DA ordering

363:    Level: intermediate

365:    Notes:
366:    The global and local vectors used here need not be the same as those
367:    obtained from DACreateGlobalVector() and DACreateNaturalVector(), BUT they
368:    must have the same parallel data layout; they could, for example, be 
369:    obtained with VecDuplicate() from the DA originating vectors.

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

373: .seealso: DAGlobalToNaturalBegin(), DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(),
374:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector(),
375:           DALocalToGlobalBegin(), DALocalToGlobalEnd()

377: @*/
378: int DANaturalToGlobalEnd(DA da,Vec g,InsertMode mode,Vec l)
379: {

386:   VecScatterEnd(g,l,mode,SCATTER_REVERSE,da->gton);
387:   return(0);
388: }