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;
196:   AO  ao;

200:   if (!da->natural) {
201:     SETERRQ(1,"Natural layout vector not yet created; cannot scatter into it");
202:   }
203:   DAGetAO(da,&ao);

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

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

222:    Collective on DA

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

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

232:    Level: advanced

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

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

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

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

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

266:    Collective on DA

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

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

276:    Level: advanced

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

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

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

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

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

307:    Collective on DA

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

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

317:    Level: advanced

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

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

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

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

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

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

352:    Collective on DA

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

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

362:    Level: intermediate

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

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

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

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

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