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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT 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 PETSCDM_DLLEXPORT DANaturalToGlobalEnd(DA da,Vec g,InsertMode mode,Vec l)
    401: {

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