Actual source code: dagtol.c

  1: #define PETSCDM_DLL

  3: /*
  4:   Code for manipulating distributed regular arrays in parallel.
  5: */

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

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

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

 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: PetscErrorCode  DALocalToGlobalBegin(DA da,Vec l,Vec g)
 86: {

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

 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: PetscErrorCode  DALocalToGlobalEnd(DA da,Vec l,Vec g)
129: {

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

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: PetscErrorCode  DAGlobalToLocalEnd(DA da,Vec g,InsertMode mode,Vec l)
171: {

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

182: EXTERN PetscErrorCode DAGetNatural_Private(DA,PetscInt*,IS*);
185: /*
186:    DAGlobalToNatural_Create - Create the global to natural scatter object

188:    Collective on DA

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

193:    Level: developer

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

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

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

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

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

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

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

239:    Collective on DA

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

246:    Output Parameter:
247: .  l  - the natural ordering values

249:    Level: advanced

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

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

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

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

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

285:    Collective on DA

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

292:    Output Parameter:
293: .  l  - the global values in the natural ordering

295:    Level: advanced

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

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

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

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

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

328:    Collective on DA

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

335:    Output Parameter:
336: .  l  - the values in the DA ordering

338:    Level: advanced

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

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

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

352: @*/
353: PetscErrorCode  DANaturalToGlobalBegin(DA da,Vec g,InsertMode mode,Vec l)
354: {

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

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

375:    Collective on DA

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

382:    Output Parameter:
383: .  l  - the global values in the PETSc DA ordering

385:    Level: intermediate

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

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

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

399: @*/
400: PetscErrorCode  DANaturalToGlobalEnd(DA da,Vec g,InsertMode mode,Vec l)
401: {

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