Actual source code: petscda.h

      1: /*
      2:       Regular array object, for easy parallelism of simple grid
      3:    problems on regular distributed arrays.
      4: */
     7:  #include petscvec.h
     8:  #include petscao.h

     11: /*S
     12:      DA - Abstract PETSc object that manages distributed field data for a single structured grid

     14:    Level: beginner

     16:   Concepts: distributed array

     18: .seealso:  DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), VecScatter
     19: S*/
     20: typedef struct _p_DA* DA;

     22: /*E
     23:     DAStencilType - Determines if the stencil extends only along the coordinate directions, or also
     24:       to the northeast, northwest etc

     26:    Level: beginner

     28: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA
     29: E*/
     30: typedef enum { DA_STENCIL_STAR,DA_STENCIL_BOX } DAStencilType;

     32: /*M
     33:      DA_STENCIL_STAR - "Star"-type stencil. In logical grid coordinates, only (i,j,k), (i+s,j,k), (i,j+s,k),
     34:                        (i,j,k+s) are in the stencil  NOT, for example, (i+s,j+s,k)

     36:      Level: beginner

     38: .seealso: DA_STENCIL_BOX, DAStencilType
     39: M*/

     41: /*M
     42:      DA_STENCIL_Box - "Box"-type stencil. In logical grid coordinates, any of (i,j,k), (i+s,j+r,k+t) may
     43:                       be in the stencil.

     45:      Level: beginner

     47: .seealso: DA_STENCIL_STAR, DAStencilType
     48: M*/

     50: /*E
     51:     DAPeriodicType - Is the domain periodic in one or more directions

     53:    Level: beginner

     55: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA
     56: E*/
     57: typedef enum { DA_NONPERIODIC,DA_XPERIODIC,DA_YPERIODIC,DA_XYPERIODIC,
     58:                DA_XYZPERIODIC,DA_XZPERIODIC,DA_YZPERIODIC,DA_ZPERIODIC}
     59:                DAPeriodicType;

     61: /*E
     62:     DAInterpolationType - Defines the type of interpolation that will be returned by
     63:        DAGetInterpolation.

     65:    Level: beginner

     67: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA, DAGetInterpolation(), DASetInterpolationType()
     68: E*/
     69: typedef enum { DA_Q0, DA_Q1 } DAInterpolationType;

     71: EXTERN PetscErrorCode DASetInterpolationType(DA,DAInterpolationType);

     73: /*E
     74:     DAElementType - Defines the type of elements that will be returned by
     75:        DAGetElements.

     77:    Level: beginner

     79: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA, DAGetInterpolation(), DASetInterpolationType(),
     80:           DASetElementType(), DAGetElements(), DARestoreElements()
     81: E*/
     82: typedef enum { DA_ELEMENT_P1, DA_ELEMENT_Q1 } DAElementType;

     84: EXTERN PetscErrorCode DASetElementType(DA,DAElementType);
     85: EXTERN PetscErrorCode DAGetElements(DA,PetscInt *,const PetscInt*[]);
     86: EXTERN PetscErrorCode DARestoreElements(DA,PetscInt *,const PetscInt*[]);

     89: #define DAXPeriodic(pt) ((pt)==DA_XPERIODIC||(pt)==DA_XYPERIODIC||(pt)==DA_XZPERIODIC||(pt)==DA_XYZPERIODIC)
     90: #define DAYPeriodic(pt) ((pt)==DA_YPERIODIC||(pt)==DA_XYPERIODIC||(pt)==DA_YZPERIODIC||(pt)==DA_XYZPERIODIC)
     91: #define DAZPeriodic(pt) ((pt)==DA_ZPERIODIC||(pt)==DA_XZPERIODIC||(pt)==DA_YZPERIODIC||(pt)==DA_XYZPERIODIC)

     93: typedef enum { DA_X,DA_Y,DA_Z } DADirection;

     98: EXTERN PetscErrorCode   DACreate1d(MPI_Comm,DAPeriodicType,PetscInt,PetscInt,PetscInt,PetscInt*,DA *);
     99: EXTERN PetscErrorCode   DACreate2d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,DA *);
    100: EXTERN PetscErrorCode   DACreate3d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,PetscInt*,DA*);
    101: EXTERN PetscErrorCode   DADestroy(DA);
    102: EXTERN PetscErrorCode   DAView(DA,PetscViewer);
    103: EXTERN PetscErrorCode   DAPrintHelp(DA);

    105: EXTERN PetscErrorCode   DAGlobalToLocalBegin(DA,Vec,InsertMode,Vec);
    106: EXTERN PetscErrorCode   DAGlobalToLocalEnd(DA,Vec,InsertMode,Vec);
    107: EXTERN PetscErrorCode   DAGlobalToNaturalBegin(DA,Vec,InsertMode,Vec);
    108: EXTERN PetscErrorCode   DAGlobalToNaturalEnd(DA,Vec,InsertMode,Vec);
    109: EXTERN PetscErrorCode   DANaturalToGlobalBegin(DA,Vec,InsertMode,Vec);
    110: EXTERN PetscErrorCode   DANaturalToGlobalEnd(DA,Vec,InsertMode,Vec);
    111: EXTERN PetscErrorCode   DALocalToLocalBegin(DA,Vec,InsertMode,Vec);
    112: EXTERN PetscErrorCode   DALocalToLocalEnd(DA,Vec,InsertMode,Vec);
    113: EXTERN PetscErrorCode   DALocalToGlobal(DA,Vec,InsertMode,Vec);
    114: EXTERN PetscErrorCode   DALocalToGlobalBegin(DA,Vec,Vec);
    115: EXTERN PetscErrorCode   DALocalToGlobalEnd(DA,Vec,Vec);
    116: EXTERN PetscErrorCode   DAGetOwnershipRange(DA,PetscInt **,PetscInt **,PetscInt **);
    117: EXTERN PetscErrorCode   DACreateGlobalVector(DA,Vec *);
    118: EXTERN PetscErrorCode   DACreateNaturalVector(DA,Vec *);
    119: EXTERN PetscErrorCode   DACreateLocalVector(DA,Vec *);
    120: EXTERN PetscErrorCode   DAGetLocalVector(DA,Vec *);
    121: EXTERN PetscErrorCode   DARestoreLocalVector(DA,Vec *);
    122: EXTERN PetscErrorCode   DAGetGlobalVector(DA,Vec *);
    123: EXTERN PetscErrorCode   DARestoreGlobalVector(DA,Vec *);
    124: EXTERN PetscErrorCode   DALoad(PetscViewer,PetscInt,PetscInt,PetscInt,DA *);
    125: EXTERN PetscErrorCode   DAGetCorners(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
    126: EXTERN PetscErrorCode   DAGetGhostCorners(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
    127: EXTERN PetscErrorCode   DAGetInfo(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,DAPeriodicType*,DAStencilType*);
    128: EXTERN PetscErrorCode   DAGetProcessorSubset(DA,DADirection,PetscInt,MPI_Comm*);
    129: EXTERN PetscErrorCode   DARefine(DA,MPI_Comm,DA*);

    131: EXTERN PetscErrorCode   DAGlobalToNaturalAllCreate(DA,VecScatter*);
    132: EXTERN PetscErrorCode   DANaturalAllToGlobalCreate(DA,VecScatter*);

    134: EXTERN PetscErrorCode   DAGetGlobalIndices(DA,PetscInt*,PetscInt**);
    135: EXTERN PetscErrorCode   DAGetISLocalToGlobalMapping(DA,ISLocalToGlobalMapping*);
    136: EXTERN PetscErrorCode   DAGetISLocalToGlobalMappingBlck(DA,ISLocalToGlobalMapping*);

    138: EXTERN PetscErrorCode   DAGetScatter(DA,VecScatter*,VecScatter*,VecScatter*);

    140: EXTERN PetscErrorCode   DAGetAO(DA,AO*);
    141: EXTERN PetscErrorCode   DASetCoordinates(DA,Vec);
    142: EXTERN PetscErrorCode   DAGetCoordinates(DA,Vec *);
    143: EXTERN PetscErrorCode   DAGetGhostedCoordinates(DA,Vec *);
    144: EXTERN PetscErrorCode   DAGetCoordinateDA(DA,DA *);
    145: EXTERN PetscErrorCode   DASetUniformCoordinates(DA,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
    146: EXTERN PetscErrorCode   DASetFieldName(DA,PetscInt,const char[]);
    147: EXTERN PetscErrorCode   DAGetFieldName(DA,PetscInt,char **);

    149: EXTERN PetscErrorCode   DAVecGetArray(DA,Vec,void *);
    150: EXTERN PetscErrorCode   DAVecRestoreArray(DA,Vec,void *);

    152: EXTERN PetscErrorCode   DASplitComm2d(MPI_Comm,PetscInt,PetscInt,PetscInt,MPI_Comm*);

    154: /*S
    155:      SDA - This provides a simplified interface to the DA distributed
    156:            array object in PETSc. This is intended for people who are
    157:            NOT using PETSc vectors or objects but just want to distribute
    158:            simple rectangular arrays amoung a number of procesors and have
    159:            PETSc handle moving the ghost-values when needed.

    161:           In certain applications this can serve as a replacement for
    162:           BlockComm (which is apparently being phased out?).

    165:    Level: beginner

    167:   Concepts: simplified distributed array

    169: .seealso:  SDACreate1d(), SDACreate2d(), SDACreate3d(), SDADestroy(), DA, SDALocalToLocalBegin(),
    170:            SDALocalToLocalEnd(), SDAGetCorners(), SDAGetGhostCorners()
    171: S*/
    172: typedef struct _SDA* SDA;

    174: EXTERN PetscErrorCode   SDACreate3d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,PetscInt*,SDA*);
    175: EXTERN PetscErrorCode   SDACreate2d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,SDA*);
    176: EXTERN PetscErrorCode   SDACreate1d(MPI_Comm,DAPeriodicType,PetscInt,PetscInt,PetscInt,PetscInt*,SDA*);
    177: EXTERN PetscErrorCode   SDADestroy(SDA);
    178: EXTERN PetscErrorCode   SDALocalToLocalBegin(SDA,PetscScalar*,InsertMode,PetscScalar*);
    179: EXTERN PetscErrorCode   SDALocalToLocalEnd(SDA,PetscScalar*,InsertMode,PetscScalar*);
    180: EXTERN PetscErrorCode   SDAGetCorners(SDA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
    181: EXTERN PetscErrorCode   SDAGetGhostCorners(SDA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);

    183: EXTERN PetscErrorCode   MatRegisterDAAD(void);
    184: EXTERN PetscErrorCode   MatCreateDAAD(DA,Mat*);

    186: /*S
    187:      DALocalInfo - C struct that contains information about a structured grid and a processors logical
    188:               location in it.

    190:    Level: beginner

    192:   Concepts: distributed array

    194:   Developer note: Then entries in this struct are int instead of PetscInt so that the elements may
    195:                   be extracted in Fortran as if from an integer array

    197: .seealso:  DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), DA, DAGetLocalInfo(), DAGetInfo()
    198: S*/
    199: typedef struct {
    200:   int            dim,dof,sw;
    201:   DAPeriodicType pt;
    202:   DAStencilType  st;
    203:   int            mx,my,mz;    /* global number of grid points in each direction */
    204:   int            xs,ys,zs;    /* starting pointd of this processor, excluding ghosts */
    205:   int            xm,ym,zm;    /* number of grid points on this processor, excluding ghosts */
    206:   int            gxs,gys,gzs;    /* starting point of this processor including ghosts */
    207:   int            gxm,gym,gzm;    /* number of grid points on this processor including ghosts */
    208:   DA             da;
    209: } DALocalInfo;

    211: /*MC
    212:       DAForEachPointBegin2d - Starts a loop over the local part of a two dimensional DA

    214:    Synopsis:
    215:    void  DAForEachPointBegin2d(DALocalInfo *info,PetscInt i,PetscInt j);
    216:
    217:    Level: intermediate

    219: .seealso: DAForEachPointEnd2d(), DAVecGetArray()
    220: M*/
    221: #define DAForEachPointBegin2d(info,i,j) {\
    222:   PetscInt _xints = info->xs,_xinte = info->xs+info->xm,_yints = info->ys,_yinte = info->ys+info->ym;\
    223:   for (j=_yints; j<_yinte; j++) {\
    224:     for (i=_xints; i<_xinte; i++) {\

    226: /*MC
    227:       DAForEachPointEnd2d - Ends a loop over the local part of a two dimensional DA

    229:    Synopsis:
    230:    void  DAForEachPointEnd2d;
    231:
    232:    Level: intermediate

    234: .seealso: DAForEachPointBegin2d(), DAVecGetArray()
    235: M*/
    236: #define DAForEachPointEnd2d }}}

    238: /*MC
    239:       DACoor2d - Structure for holding 2d (x and y) coordinates.

    241:     Level: intermediate

    243:     Sample Usage:
    244:       DACoor2d **coors;
    245:       Vec      vcoors;
    246:       DA       cda;

    248:       DAGetCoordinates(da,&vcoors);
    249:       DAGetCoordinateDA(da,&cda);
    250:       DAVecGetArray(dac,vcoors,&coors);
    251:       DAGetCorners(dac,&mstart,&nstart,0,&m,&n,0)
    252:       for (i=mstart; i<mstart+m; i++) {
    253:         for (j=nstart; j<nstart+n; j++) {
    254:           x = coors[j][i].x;
    255:           y = coors[j][i].y;
    256:           ......
    257:         }
    258:       }
    259:       DAVecRestoreArray(dac,vcoors,&coors);

    261: .seealso: DACoor3d, DAForEachPointBegin(), DAGetCoordinateDA(), DAGetCoordinates(), DAGetGhostCoordinates()
    262: M*/
    263: typedef struct {PetscScalar x,y;} DACoor2d;

    265: /*MC
    266:       DACoor3d - Structure for holding 3d (x, y and z) coordinates.

    268:     Level: intermediate

    270:     Sample Usage:
    271:       DACoor3d **coors;
    272:       Vec      vcoors;
    273:       DA       cda;

    275:       DAGetCoordinates(da,&vcoors);
    276:       DAGetCoordinateDA(da,&cda);
    277:       DAVecGetArray(dac,vcoors,&coors);
    278:       DAGetCorners(dac,&mstart,&nstart,&pstart,&m,&n,&p)
    279:       for (i=mstart; i<mstart+m; i++) {
    280:         for (j=nstart; j<nstart+n; j++) {
    281:           for (k=pstart; k<pstart+p; k++) {
    282:             x = coors[k][j][i].x;
    283:             y = coors[k][j][i].y;
    284:             z = coors[k][j][i].z;
    285:           ......
    286:         }
    287:       }
    288:       DAVecRestoreArray(dac,vcoors,&coors);

    290: .seealso: DACoor2d, DAForEachPointBegin(), DAGetCoordinateDA(), DAGetCoordinates(), DAGetGhostCoordinates()
    291: M*/
    292: typedef struct {PetscScalar x,y,z;} DACoor3d;
    293:
    294: EXTERN PetscErrorCode DAGetLocalInfo(DA,DALocalInfo*);
    295: typedef PetscErrorCode (*DALocalFunction1)(DALocalInfo*,void*,void*,void*);
    296: EXTERN PetscErrorCode DAFormFunction1(DA,Vec,Vec,void*);
    297: EXTERN PetscErrorCode DAFormFunctioni1(DA,PetscInt,Vec,PetscScalar*,void*);
    298: EXTERN PetscErrorCode DAComputeJacobian1WithAdic(DA,Vec,Mat,void*);
    299: EXTERN PetscErrorCode DAComputeJacobian1WithAdifor(DA,Vec,Mat,void*);
    300: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAdic(DA,Vec,Vec,Vec,void*);
    301: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAdifor(DA,Vec,Vec,Vec,void*);
    302: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAD(DA,Vec,Vec,Vec,void*);
    303: EXTERN PetscErrorCode DAComputeJacobian1(DA,Vec,Mat,void*);
    304: EXTERN PetscErrorCode DAGetLocalFunction(DA,DALocalFunction1*);
    305: EXTERN PetscErrorCode DASetLocalFunction(DA,DALocalFunction1);
    306: EXTERN PetscErrorCode DASetLocalFunctioni(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*));
    307: EXTERN PetscErrorCode DASetLocalJacobian(DA,DALocalFunction1);
    308: EXTERN PetscErrorCode DASetLocalAdicFunction_Private(DA,DALocalFunction1);

    310: /*MC
    311:        DASetLocalAdicFunction - Caches in a DA a local function computed by ADIC/ADIFOR

    313:    Collective on DA

    315:    Synopsis:
    316:    PetscErrorCode DASetLocalAdicFunction(DA da,DALocalFunction1 ad_lf)
    317:
    318:    Input Parameter:
    319: +  da - initial distributed array
    320: -  ad_lf - the local function as computed by ADIC/ADIFOR

    322:    Level: intermediate

    324: .keywords:  distributed array, refine

    326: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), DAGetLocalFunction(), DASetLocalFunction(),
    327:           DASetLocalJacobian()
    328: M*/
    329: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    330: #  define DASetLocalAdicFunction(a,d) DASetLocalAdicFunction_Private(a,(DALocalFunction1)d)
    331: #else
    332: #  define DASetLocalAdicFunction(a,d) DASetLocalAdicFunction_Private(a,0)
    333: #endif

    335: EXTERN PetscErrorCode DASetLocalAdicMFFunction_Private(DA,DALocalFunction1);
    336: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    337: #  define DASetLocalAdicMFFunction(a,d) DASetLocalAdicMFFunction_Private(a,(DALocalFunction1)d)
    338: #else
    339: #  define DASetLocalAdicMFFunction(a,d) DASetLocalAdicMFFunction_Private(a,0)
    340: #endif
    341: EXTERN PetscErrorCode DASetLocalAdicFunctioni_Private(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*));
    342: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    343: #  define DASetLocalAdicFunctioni(a,d) DASetLocalAdicFunctioni_Private(a,(PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*))d)
    344: #else
    345: #  define DASetLocalAdicFunctioni(a,d) DASetLocalAdicFunctioni_Private(a,0)
    346: #endif
    347: EXTERN PetscErrorCode DASetLocalAdicMFFunctioni_Private(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*));
    348: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    349: #  define DASetLocalAdicMFFunctioni(a,d) DASetLocalAdicMFFunctioni_Private(a,(PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*))d)
    350: #else
    351: #  define DASetLocalAdicMFFunctioni(a,d) DASetLocalAdicMFFunctioni_Private(a,0)
    352: #endif
    353: EXTERN PetscErrorCode DAFormFunctioniTest1(DA,void*);

    355:  #include petscmat.h
    356: EXTERN PetscErrorCode DAGetColoring(DA,ISColoringType,ISColoring *);
    357: EXTERN PetscErrorCode DAGetMatrix(DA,const MatType,Mat *);
    358: EXTERN PetscErrorCode DASetGetMatrix(DA,PetscErrorCode (*)(DA,const MatType,Mat *));
    359: EXTERN PetscErrorCode DAGetInterpolation(DA,DA,Mat*,Vec*);
    360: EXTERN PetscErrorCode DAGetInjection(DA,DA,VecScatter*);
    361: EXTERN PetscErrorCode DASetBlockFills(DA,PetscInt*,PetscInt*);
    362: EXTERN PetscErrorCode DASetRefinementFactor(DA,PetscInt,PetscInt,PetscInt);
    363: EXTERN PetscErrorCode DAGetRefinementFactor(DA,PetscInt*,PetscInt*,PetscInt*);

    365: EXTERN PetscErrorCode DAGetAdicArray(DA,PetscTruth,void**,void**,PetscInt*);
    366: EXTERN PetscErrorCode DARestoreAdicArray(DA,PetscTruth,void**,void**,PetscInt*);
    367: EXTERN PetscErrorCode DAGetAdicMFArray(DA,PetscTruth,void**,void**,PetscInt*);
    368: EXTERN PetscErrorCode DARestoreAdicMFArray(DA,PetscTruth,void**,void**,PetscInt*);
    369: EXTERN PetscErrorCode DAGetArray(DA,PetscTruth,void**);
    370: EXTERN PetscErrorCode DARestoreArray(DA,PetscTruth,void**);
    371: EXTERN PetscErrorCode ad_DAGetArray(DA,PetscTruth,void**);
    372: EXTERN PetscErrorCode ad_DARestoreArray(DA,PetscTruth,void**);
    373: EXTERN PetscErrorCode admf_DAGetArray(DA,PetscTruth,void**);
    374: EXTERN PetscErrorCode admf_DARestoreArray(DA,PetscTruth,void**);

    376:  #include petscpf.h
    377: EXTERN PetscErrorCode DACreatePF(DA,PF*);

    379: /*S
    380:      VecPack - Abstract PETSc object that manages treating several distinct vectors as if they
    381:         were one.   The VecPack routines allow one to manage a nonlinear solver that works on a
    382:         vector that consists of several distinct parts. This is mostly used for LNKS solvers,
    383:         that is design optimization problems that are written as a nonlinear system

    385:    Level: beginner

    387:   Concepts: multi-component, LNKS solvers

    389: .seealso:  VecPackCreate(), VecPackDestroy()
    390: S*/
    391: typedef struct _p_VecPack *VecPack;

    393: EXTERN PetscErrorCode VecPackCreate(MPI_Comm,VecPack*);
    394: EXTERN PetscErrorCode VecPackDestroy(VecPack);
    395: EXTERN PetscErrorCode VecPackAddArray(VecPack,PetscInt);
    396: EXTERN PetscErrorCode VecPackAddDA(VecPack,DA);
    397: EXTERN PetscErrorCode VecPackAddVecScatter(VecPack,VecScatter);
    398: EXTERN PetscErrorCode VecPackScatter(VecPack,Vec,...);
    399: EXTERN PetscErrorCode VecPackGather(VecPack,Vec,...);
    400: EXTERN PetscErrorCode VecPackGetAccess(VecPack,Vec,...);
    401: EXTERN PetscErrorCode VecPackRestoreAccess(VecPack,Vec,...);
    402: EXTERN PetscErrorCode VecPackGetLocalVectors(VecPack,...);
    403: EXTERN PetscErrorCode VecPackGetEntries(VecPack,...);
    404: EXTERN PetscErrorCode VecPackRestoreLocalVectors(VecPack,...);
    405: EXTERN PetscErrorCode VecPackCreateGlobalVector(VecPack,Vec*);
    406: EXTERN PetscErrorCode VecPackGetGlobalIndices(VecPack,...);
    407: EXTERN PetscErrorCode VecPackRefine(VecPack,MPI_Comm,VecPack*);
    408: EXTERN PetscErrorCode VecPackGetInterpolation(VecPack,VecPack,Mat*,Vec*);

    410:  #include petscsnes.h

    412: /*S
    413:      DM - Abstract PETSc object that manages an abstract grid object
    414:
    415:    Level: intermediate

    417:   Concepts: grids, grid refinement

    419:    Notes: The DA object and the VecPack object are examples of DMs

    421:           Though the DA objects require the petscsnes.h include files the DM library is
    422:     NOT dependent on the SNES or KSP library. In fact, the KSP and SNES libraries depend on
    423:     DM. (This is not great design, but not trivial to fix).

    425: .seealso:  VecPackCreate(), DA, VecPack
    426: S*/
    427: typedef struct _p_DM* DM;

    429: EXTERN PetscErrorCode DMView(DM,PetscViewer);
    430: EXTERN PetscErrorCode DMDestroy(DM);
    431: EXTERN PetscErrorCode DMCreateGlobalVector(DM,Vec*);
    432: EXTERN PetscErrorCode DMGetColoring(DM,ISColoringType,ISColoring*);
    433: EXTERN PetscErrorCode DMGetMatrix(DM,const MatType,Mat*);
    434: EXTERN PetscErrorCode DMGetInterpolation(DM,DM,Mat*,Vec*);
    435: EXTERN PetscErrorCode DMGetInjection(DM,DM,VecScatter*);
    436: EXTERN PetscErrorCode DMRefine(DM,MPI_Comm,DM*);
    437: EXTERN PetscErrorCode DMGetInterpolationScale(DM,DM,Mat,Vec*);

    439: typedef struct NLF_DAAD* NLF;

    441: /*S
    442:      DMMG -  Data structure to easily manage multi-level non-linear solvers on grids managed by DM
    443:
    444:    Level: intermediate

    446:   Concepts: multigrid, Newton-multigrid

    448: .seealso:  VecPackCreate(), DA, VecPack, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES()
    449: S*/
    450: typedef struct _p_DMMG *DMMG;
    451: struct _p_DMMG {
    452:   DM             dm;                   /* grid information for this level */
    453:   Vec            x,b,r;                /* global vectors used in multigrid preconditioner for this level*/
    454:   Mat            J;                    /* matrix on this level */
    455:   Mat            R;                    /* restriction to next coarser level (not defined on level 0) */
    456:   PetscInt       nlevels;              /* number of levels above this one (total number of levels on level 0)*/
    457:   MPI_Comm       comm;
    458:   PetscErrorCode (*solve)(DMMG*,PetscInt);
    459:   void           *user;
    460:   PetscTruth     galerkin;                  /* for A_c = R*A*R^T */

    462:   /* KSP only */
    463:   KSP            ksp;
    464:   PetscErrorCode (*rhs)(DMMG,Vec);
    465:   PetscTruth     matricesset;               /* User had called DMMGSetKSP() and the matrices have been computed */

    467:   /* SNES only */
    468:   Mat            B;
    469:   Vec            Rscale;                 /* scaling to restriction before computing Jacobian */
    470:   PetscErrorCode (*computejacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
    471:   PetscErrorCode (*computefunction)(SNES,Vec,Vec,void*);

    473:   PetscTruth     updatejacobian;         /* compute new Jacobian when DMMGComputeJacobian_Multigrid() is called */
    474:   PetscInt       updatejacobianperiod;   /* how often, inside a SNES, the Jacobian is recomputed */

    476:   MatFDColoring  fdcoloring;             /* only used with FD coloring for Jacobian */
    477:   SNES           snes;
    478:   PetscErrorCode (*initialguess)(DMMG,Vec);
    479:   Vec            w,work1,work2;         /* global vectors */
    480:   Vec            lwork1;

    482:   /* FAS only */
    483:   NLF            nlf;                   /* FAS smoother object */
    484:   VecScatter     inject;                /* inject from this level to the next coarsest */
    485:   PetscTruth     monitor,monitorall;
    486:   PetscInt       presmooth,postsmooth,coarsesmooth;
    487:   PetscReal      rtol,abstol,rrtol;       /* convergence tolerance */
    488:
    489: };

    491: EXTERN PetscErrorCode DMMGCreate(MPI_Comm,PetscInt,void*,DMMG**);
    492: EXTERN PetscErrorCode DMMGDestroy(DMMG*);
    493: EXTERN PetscErrorCode DMMGSetUp(DMMG*);
    494: EXTERN PetscErrorCode DMMGSetKSP(DMMG*,PetscErrorCode (*)(DMMG,Vec),PetscErrorCode (*)(DMMG,Mat));
    495: EXTERN PetscErrorCode DMMGSetSNES(DMMG*,PetscErrorCode (*)(SNES,Vec,Vec,void*),PetscErrorCode (*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
    496: EXTERN PetscErrorCode DMMGSetInitialGuess(DMMG*,PetscErrorCode (*)(DMMG,Vec));
    497: EXTERN PetscErrorCode DMMGInitialGuessCurrent(DMMG,Vec);
    498: EXTERN PetscErrorCode DMMGView(DMMG*,PetscViewer);
    499: EXTERN PetscErrorCode DMMGSolve(DMMG*);
    500: EXTERN PetscErrorCode DMMGSetUseMatrixFree(DMMG*);
    501: EXTERN PetscErrorCode DMMGSetDM(DMMG*,DM);
    502: EXTERN PetscErrorCode DMMGSetUpLevel(DMMG*,KSP,PetscInt);
    503: EXTERN PetscErrorCode DMMGSetUseGalerkinCoarse(DMMG*);
    504: EXTERN PetscErrorCode DMMGSetNullSpace(DMMG*,PetscTruth,PetscInt,PetscErrorCode (*)(DMMG,Vec[]));

    506: EXTERN PetscErrorCode DMMGSetSNESLocal_Private(DMMG*,DALocalFunction1,DALocalFunction1,DALocalFunction1,DALocalFunction1);
    507: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    508: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) \
    509:   DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)(ad_function),(DALocalFunction1)(admf_function))
    510: #else
    511: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)0,(DALocalFunction1)0)
    512: #endif

    514: EXTERN PetscErrorCode DMMGSetSNESLocali_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
    515: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
    516: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*))(ad_function),(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*))(admf_function))
    517: #else
    518: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
    519: #endif

    521: /*MC
    522:    DMMGGetb - Returns the right hand side vector from a DMMG solve on the finest grid

    524:    Synopsis:
    525:    Vec DMMGGetb(DMMG *dmmg)

    527:    Not Collective, but resulting vector is parallel

    529:    Input Parameters:
    530: .   dmmg - DMMG solve context

    532:    Level: intermediate

    534:    Fortran Usage:
    535: .     DMMGGetb(DMMG dmmg,Vec b,PetscErrorCode ierr)

    537: .seealso: DMMGCreate(), DMMGSetSNES(), DMMGSetKSP(), DMMGSetSNESLocal(), DMMGGetb()

    539: M*/
    540: #define DMMGGetb(ctx)              (ctx)[(ctx)[0]->nlevels-1]->b

    542: #define DMMGGetr(ctx)              (ctx)[(ctx)[0]->nlevels-1]->r

    544: /*MC
    545:    DMMGGetx - Returns the solution vector from a DMMG solve on the finest grid

    547:    Synopsis:
    548:    Vec DMMGGetx(DMMG *dmmg)

    550:    Not Collective, but resulting vector is parallel

    552:    Input Parameters:
    553: .   dmmg - DMMG solve context

    555:    Level: intermediate

    557:    Fortran Usage:
    558: .     DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)

    560: .seealso: DMMGCreate(), DMMGSetSNES(), DMMGSetKSP(), DMMGSetSNESLocal()

    562: M*/
    563: #define DMMGGetx(ctx)              (ctx)[(ctx)[0]->nlevels-1]->x

    565: /*MC
    566:    DMMGGetJ - Returns the Jacobian (matrix) for the finest level

    568:    Synopsis:
    569:    Mat DMMGGetJ(DMMG *dmmg)

    571:    Not Collective

    573:    Input Parameter:
    574: .   dmmg - DMMG solve context

    576:    Level: intermediate

    578: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetB()

    580: M*/
    581: #define DMMGGetJ(ctx)              (ctx)[(ctx)[0]->nlevels-1]->J

    583: /*MC
    584:    DMMGGetComm - Returns the MPI_Comm for the finest level

    586:    Synopsis:
    587:    MPI_Comm DMMGGetJ(DMMG *dmmg)

    589:    Not Collective

    591:    Input Parameter:
    592: .   dmmg - DMMG solve context

    594:    Level: intermediate

    596: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()

    598: M*/
    599: #define DMMGGetComm(ctx)           (ctx)[(ctx)[0]->nlevels-1]->comm

    601: /*MC
    602:    DMMGGetB - Returns the matrix for the finest level used to construct the preconditioner; usually
    603:               the same as the Jacobian

    605:    Synopsis:
    606:    Mat DMMGGetJ(DMMG *dmmg)

    608:    Not Collective

    610:    Input Parameter:
    611: .   dmmg - DMMG solve context

    613:    Level: intermediate

    615: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()

    617: M*/
    618: #define DMMGGetB(ctx)              (ctx)[(ctx)[0]->nlevels-1]->B

    620: /*MC
    621:    DMMGGetFine - Returns the DMMG associated with the finest level

    623:    Synopsis:
    624:    DMMG DMMGGetFine(DMMG *dmmg)

    626:    Not Collective

    628:    Input Parameter:
    629: .   dmmg - DMMG solve context

    631:    Level: intermediate

    633: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()

    635: M*/
    636: #define DMMGGetFine(ctx)           (ctx)[(ctx)[0]->nlevels-1]

    639: /*MC
    640:    DMMGGetKSP - Gets the KSP object (linear solver object) for the finest level

    642:    Synopsis:
    643:    KSP DMMGGetKSP(DMMG *dmmg)

    645:    Not Collective

    647:    Input Parameter:
    648: .   dmmg - DMMG solve context

    650:    Level: intermediate

    652:    Notes: If this is a linear problem (i.e. DMMGSetKSP() was used) then this is the
    653:      master linear solver. If this is a nonlinear problem (i.e. DMMGSetSNES() was used) this
    654:      returns the KSP (linear solver) that is associated with the SNES (nonlinear solver)

    656: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetSNES()

    658: M*/
    659: #define DMMGGetKSP(ctx)            (ctx)[(ctx)[0]->nlevels-1]->ksp

    661: /*MC
    662:    DMMGGetSNES - Gets the SNES object (nonlinear solver) for the finest level

    664:    Synopsis:
    665:    SNES DMMGGetSNES(DMMG *dmmg)

    667:    Not Collective

    669:    Input Parameter:
    670: .   dmmg - DMMG solve context

    672:    Level: intermediate

    674:    Notes: If this is a linear problem (i.e. DMMGSetKSP() was used) then this returns PETSC_NULL

    676: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP()

    678: M*/
    679: #define DMMGGetSNES(ctx)           (ctx)[(ctx)[0]->nlevels-1]->snes

    681: /*MC
    682:    DMMGGetDA - Gets the DA object on the finest level

    684:    Synopsis:
    685:    DA DMMGGetDA(DMMG *dmmg)

    687:    Not Collective

    689:    Input Parameter:
    690: .   dmmg - DMMG solve context

    692:    Level: intermediate

    694:    Notes: Use only if the DMMG was created with a DA, not a VecPack

    696: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP(), DMMGGetVecPack()

    698: M*/
    699: #define DMMGGetDA(ctx)             (DA)((ctx)[(ctx)[0]->nlevels-1]->dm)

    701: /*MC
    702:    DMMGGetVecPack - Gets the VecPack object on the finest level

    704:    Synopsis:
    705:    VecPack DMMGGetVecPack(DMMG *dmmg)

    707:    Not Collective

    709:    Input Parameter:
    710: .   dmmg - DMMG solve context

    712:    Level: intermediate

    714:    Notes: Use only if the DMMG was created with a DA, not a VecPack

    716: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP(), DMMGGetDA()

    718: M*/
    719: #define DMMGGetVecPack(ctx)        (VecPack)((ctx)[(ctx)[0]->nlevels-1]->dm)

    721: /*MC
    722:    DMMGGetUser - Returns the user context for a particular level

    724:    Synopsis:
    725:    void* DMMGGetUser(DMMG *dmmg,PetscInt level)

    727:    Not Collective

    729:    Input Parameters:
    730: +   dmmg - DMMG solve context
    731: -   level - the number of the level you want the context for

    733:    Level: intermediate

    735: .seealso: DMMGCreate(), DMMGSetUser()

    737: M*/
    738: #define DMMGGetUser(ctx,level)     ((ctx)[level]->user)

    740: /*MC
    741:    DMMGSetUser - Sets the user context for a particular level

    743:    Synopsis:
    744:    PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)

    746:    Not Collective

    748:    Input Parameters:
    749: +   dmmg - DMMG solve context
    750: .   level - the number of the level you want the context for
    751: -   ctx - the context

    753:    Level: intermediate

    755:    Note: if the context is the same for each level just pass it in with
    756:          DMMGCreate() and don't call this macro

    758: .seealso: DMMGCreate(), DMMGGetUser()

    760: M*/
    761: #define DMMGSetUser(ctx,level,usr) ((ctx)[level]->user = usr,0)

    763: /*MC
    764:    DMMGGetLevels - Gets the number of levels in a DMMG object

    766:    Synopsis:
    767:    PetscInt DMMGGetLevels(DMMG *dmmg)

    769:    Not Collective

    771:    Input Parameter:
    772: .   dmmg - DMMG solve context

    774:    Level: intermediate

    776: .seealso: DMMGCreate(), DMMGGetUser()

    778: M*/
    779: #define DMMGGetLevels(ctx)         (ctx)[0]->nlevels

    781: /*MC
    782:    DMMGGetDMMG - Returns the DMMG struct for the finest level

    784:    Synopsis:
    785:    DMMG DMMGGetDMMG(DMMG *dmmg)

    787:    Not Collective

    789:    Input Parameter:
    790: .   dmmg - DMMG solve context

    792:    Level: intermediate

    794: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetB()

    796: M*/
    797: #define DMMGGetDMMG(ctx)              (ctx)[(ctx)[0]->nlevels-1]

    800: #endif