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: #undef __FUNCT__  
 11: /*@
 12:    DAGlobalToLocalBegin - Maps values from the global vector to the local
 13:    patch; the ghost points are included. Must be followed by 
 14:    DAGlobalToLocalEnd() to complete the exchange.

 16:    Collective on DA

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

 23:    Output Parameter:
 24: .  l  - the local values

 26:    Level: beginner

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

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

 36: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
 37:           DALocalToLocalBegin(), DALocalToLocalEnd(),
 38:           DALocalToGlobalBegin(), DALocalToGlobalEnd()
 39:           

 41: @*/
 42: int DAGlobalToLocalBegin(DA da,Vec g,InsertMode mode,Vec l)
 43: {

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

 54: #undef __FUNCT__  
 56: /*@
 57:    DALocalToGlobalBegin - Adds values from the local (ghosted) vector
 58:    into the global (nonghosted) vector.

 60:    Collective on DA

 62:    Input Parameters:
 63: +  da - the distributed array context
 64: -  l  - the local values

 66:    Output Parameter:
 67: .  g - the global vector

 69:    Level: beginner

 71:    Notes:
 72:    Use DALocalToGlobal() to discard the ghost point values

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

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

 81: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
 82:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalEnd()

 84: @*/
 85: int DALocalToGlobalBegin(DA da,Vec l,Vec g)
 86: {

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

 97: #undef __FUNCT__  
 99: /*@
100:    DALocalToGlobalEnd - Adds values from the local (ghosted) vector
101:    into the global (nonghosted) vector.

103:    Collective on DA

105:    Input Parameters:
106: +  da - the distributed array context
107: -  l  - the local values

109:    Output Parameter:
110: .  g - the global vector

112:    Level: beginner

114:    Notes:
115:    Use DALocalToGlobal() to discard the ghost point values

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

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

124: .seealso: DAGlobalToLocalEnd(), DALocalToGlobal(), DACreate2d(), 
125:           DALocalToLocalBegin(), DALocalToLocalEnd(), DALocalToGlobalBegin()

127: @*/
128: int DALocalToGlobalEnd(DA da,Vec l,Vec g)
129: {

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

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

147:    Collective on DA

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

154:    Output Parameter:
155: .  l  - the local values

157:    Level: beginner

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

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

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

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

182: #undef __FUNCT__  
184: /*
185:    DAGlobalToNatural_Create - Create the global to natural scatter object

187:    Collective on DA

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

192:    Level: developer

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

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

199: .seealso: DAGlobalToNaturalEnd(), DALocalToGlobal(), DACreate2d(), 
200:           DAGlobalToLocalBegin(), DAGlobalToLocalEnd(), DACreateNaturalVector()
201: */
202: int DAGlobalToNatural_Create(DA da)
203: {
204:   int ierr,m,start;
205:   IS  from,to;
206:   AO  ao;
207:   Vec global;

211:   if (!da->natural) {
212:     SETERRQ(1,"Natural layout vector not yet created; cannot scatter into it");
213:   }
214:   DAGetAO(da,&ao);

216:   /* create the scatter context */
217:   VecGetLocalSize(da->natural,&m);
218:   VecGetOwnershipRange(da->natural,&start,PETSC_NULL);
219:   ISCreateStride(da->comm,m,start,1,&to);
220:   AOPetscToApplicationIS(ao,to);
221:   ISCreateStride(da->comm,m,start,1,&from);
222:   VecCreateMPIWithArray(da->comm,da->Nlocal,PETSC_DETERMINE,0,&global);
223:   VecScatterCreate(global,from,da->natural,to,&da->gton);
224:   VecDestroy(global);
225:   ISDestroy(from);
226:   ISDestroy(to);
227:   return(0);
228: }

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

237:    Collective on DA

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

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

247:    Level: advanced

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

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

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

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

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

283:    Collective on DA

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

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

293:    Level: advanced

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

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

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

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

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

326:    Collective on DA

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

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

336:    Level: advanced

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

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

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

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

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

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

373:    Collective on DA

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

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

383:    Level: intermediate

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

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

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

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

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