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(da->gtol,g,l,mode,SCATTER_FORWARD);
 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(da->gtol,l,g,ADD_VALUES,SCATTER_REVERSE);
 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(da->gtol,l,g,ADD_VALUES,SCATTER_REVERSE);
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(da->gtol,g,l,mode,SCATTER_FORWARD);
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(((PetscObject)da)->comm,m,start,1,&from);
223:   VecCreateMPIWithArray(((PetscObject)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:    You must call DACreateNaturalVector() before using this routine

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

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

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

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

287:    Collective on DA

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

294:    Output Parameter:
295: .  l  - the global values in the natural ordering

297:    Level: advanced

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

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

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

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

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

330:    Collective on DA

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

337:    Output Parameter:
338: .  l  - the values in the DA ordering

340:    Level: advanced

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

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

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

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

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

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

377:    Collective on DA

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

384:    Output Parameter:
385: .  l  - the global values in the PETSc DA ordering

387:    Level: intermediate

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

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

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

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

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