Actual source code: petscdmmg.h

  1: /*
  2:   Defines the interface functions for the DMMG object.
  3: */
  4: #ifndef __PETSCDMMG_H
 6:  #include petscsnes.h
 7:  #include petscda.h

 10: /*S
 11:      DMMG -  Data structure to easily manage multi-level non-linear solvers on grids managed by DM
 12:           
 13:    Level: intermediate

 15:   Concepts: multigrid, Newton-multigrid

 17: .seealso:  VecPackCreate(), DA, VecPack, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES()
 18: S*/
 19: typedef struct _n_DMMG* DMMG;
 20: struct _n_DMMG {
 21:   DM             dm;                   /* grid information for this level */
 22:   Vec            x,b,r;                /* global vectors used in multigrid preconditioner for this level*/
 23:   Mat            J;                    /* matrix on this level */
 24:   Mat            B;
 25:   Mat            R;                    /* restriction to next coarser level (not defined on level 0) */
 26:   PetscInt       nlevels;              /* number of levels above this one (total number of levels on level 0)*/
 27:   MPI_Comm       comm;
 28:   PetscErrorCode (*solve)(DMMG*,PetscInt);
 29:   void           *user;
 30:   PetscTruth     galerkin;                  /* for A_c = R*A*R^T */

 32:   /* KSP only */
 33:   KSP            ksp;
 34:   PetscErrorCode (*rhs)(DMMG,Vec);
 35:   PetscTruth     matricesset;               /* User had called DMMGSetKSP() and the matrices have been computed */

 37:   /* SNES only */
 38:   Vec            Rscale;                 /* scaling to restriction before computing Jacobian */
 39:   PetscErrorCode (*computejacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
 40:   PetscErrorCode (*computefunction)(SNES,Vec,Vec,void*);

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

 45:   MatFDColoring  fdcoloring;             /* only used with FD coloring for Jacobian */
 46:   SNES           snes;
 47:   PetscErrorCode (*initialguess)(DMMG,Vec);
 48:   Vec            w,work1,work2;         /* global vectors */
 49:   Vec            lwork1;

 51:   PetscErrorCode (*lfj)(void);          /* function used when computing Jacobian via FD, usually da->lf */

 53:   /* FAS only */
 54:   NLF            nlf;                   /* FAS smoother object */
 55:   VecScatter     inject;                /* inject from this level to the next coarsest */
 56:   PetscTruth     monitor,monitorall;
 57:   PetscInt       presmooth,postsmooth,coarsesmooth;
 58:   PetscReal      rtol,abstol,rrtol;       /* convergence tolerance */
 59: 
 60: };

 62: EXTERN PetscErrorCode  DMMGCreate(MPI_Comm,PetscInt,void*,DMMG**);
 63: EXTERN PetscErrorCode  DMMGDestroy(DMMG*);
 64: EXTERN PetscErrorCode  DMMGSetUp(DMMG*);
 65: EXTERN PetscErrorCode  DMMGSetKSP(DMMG*,PetscErrorCode (*)(DMMG,Vec),PetscErrorCode (*)(DMMG,Mat,Mat));
 66: EXTERN PetscErrorCode  DMMGSetSNES(DMMG*,PetscErrorCode (*)(SNES,Vec,Vec,void*),PetscErrorCode (*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));

 68: EXTERN PetscErrorCode  DMMGSetInitialGuessLocal(DMMG*,PetscErrorCode (*)(DALocalInfo*,void*));
 69: EXTERN PetscErrorCode  DMMGSetInitialGuess(DMMG*,PetscErrorCode (*)(DMMG,Vec));
 70: EXTERN PetscErrorCode  DMMGInitialGuessCurrent(DMMG,Vec);
 71: EXTERN PetscErrorCode  DMMGView(DMMG*,PetscViewer);
 72: EXTERN PetscErrorCode  DMMGSolve(DMMG*);
 73: EXTERN PetscErrorCode  DMMGSetUseMatrixFree(DMMG*);
 74: EXTERN PetscErrorCode  DMMGSetDM(DMMG*,DM);
 75: EXTERN PetscErrorCode  DMMGSetUpLevel(DMMG*,KSP,PetscInt);
 76: EXTERN PetscErrorCode  DMMGSetUseGalerkinCoarse(DMMG*);
 77: EXTERN PetscErrorCode  DMMGSetNullSpace(DMMG*,PetscTruth,PetscInt,PetscErrorCode (*)(DMMG,Vec[]));

 79: EXTERN PetscErrorCode  DMMGSetSNESLocal_Private(DMMG*,DALocalFunction1,DALocalFunction1,DALocalFunction1,DALocalFunction1);
 80: #if defined(PETSC_HAVE_ADIC)
 81: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) \
 82:   DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)(ad_function),(DALocalFunction1)(admf_function))
 83: #else
 84: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)0,(DALocalFunction1)0)
 85: #endif

 87: EXTERN PetscErrorCode  DMMGSetSNESLocali_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
 88: #if defined(PETSC_HAVE_ADIC)
 89: #  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))
 90: #else
 91: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
 92: #endif

 94: EXTERN PetscErrorCode  DMMGSetSNESLocalib_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
 95: #if defined(PETSC_HAVE_ADIC)
 96: #  define DMMGSetSNESLocalib(dmmg,function,ad_function,admf_function) DMMGSetSNESLocalib_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))
 97: #else
 98: #  define DMMGSetSNESLocalib(dmmg,function,ad_function,admf_function) DMMGSetSNESLocalib_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
 99: #endif


103: /*MC
104:    DMMGGetRHS - Returns the right hand side vector from a DMMG solve on the finest grid

106:    Synopsis:
107:    Vec DMMGGetRHS(DMMG *dmmg)

109:    Not Collective, but resulting vector is parallel

111:    Input Parameters:
112: .   dmmg - DMMG solve context

114:    Level: intermediate

116:    Fortran Usage:
117: .     DMMGGetRHS(DMMG dmmg,Vec b,PetscErrorCode ierr)

119: .seealso: DMMGCreate(), DMMGSetSNES(), DMMGSetKSP(), DMMGSetSNESLocal(), DMMGGetRHS()

121: M*/
122: #define DMMGGetRHS(ctx)              (ctx)[(ctx)[0]->nlevels-1]->b

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

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

129:    Synopsis:
130:    Vec DMMGGetx(DMMG *dmmg)

132:    Not Collective, but resulting vector is parallel

134:    Input Parameters:
135: .   dmmg - DMMG solve context

137:    Level: intermediate

139:    Fortran Usage:
140: .     DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)

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

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

147: /*MC
148:    DMMGGetJ - Returns the Jacobian (matrix) for the finest level

150:    Synopsis:
151:    Mat DMMGGetJ(DMMG *dmmg)

153:    Not Collective

155:    Input Parameter:
156: .   dmmg - DMMG solve context

158:    Level: intermediate

160: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetB(), DMMGGetRHS()

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

165: /*MC
166:    DMMGGetComm - Returns the MPI_Comm for the finest level

168:    Synopsis:
169:    MPI_Comm DMMGGetJ(DMMG *dmmg)

171:    Not Collective

173:    Input Parameter:
174: .   dmmg - DMMG solve context

176:    Level: intermediate

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

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

183: /*MC
184:    DMMGGetB - Returns the matrix for the finest level used to construct the preconditioner; usually 
185:               the same as the Jacobian

187:    Synopsis:
188:    Mat DMMGGetJ(DMMG *dmmg)

190:    Not Collective

192:    Input Parameter:
193: .   dmmg - DMMG solve context

195:    Level: intermediate

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

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

202: /*MC
203:    DMMGGetFine - Returns the DMMG associated with the finest level

205:    Synopsis:
206:    DMMG DMMGGetFine(DMMG *dmmg)

208:    Not Collective

210:    Input Parameter:
211: .   dmmg - DMMG solve context

213:    Level: intermediate

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

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


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

224:    Synopsis:
225:    KSP DMMGGetKSP(DMMG *dmmg)

227:    Not Collective

229:    Input Parameter:
230: .   dmmg - DMMG solve context

232:    Level: intermediate

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

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

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

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

246:    Synopsis:
247:    SNES DMMGGetSNES(DMMG *dmmg)

249:    Not Collective

251:    Input Parameter:
252: .   dmmg - DMMG solve context

254:    Level: intermediate

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

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

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

263: /*MC
264:    DMMGGetDA - Gets the DA object on the finest level

266:    Synopsis:
267:    DA DMMGGetDA(DMMG *dmmg)

269:    Not Collective

271:    Input Parameter:
272: .   dmmg - DMMG solve context

274:    Level: intermediate

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

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

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

283: /*MC
284:    DMMGGetVecPack - Gets the VecPack object on the finest level

286:    Synopsis:
287:    VecPack DMMGGetVecPack(DMMG *dmmg)

289:    Not Collective

291:    Input Parameter:
292: .   dmmg - DMMG solve context

294:    Level: intermediate

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

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

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

303: /*MC
304:    DMMGGetUser - Returns the user context for a particular level

306:    Synopsis:
307:    void* DMMGGetUser(DMMG *dmmg,PetscInt level)

309:    Not Collective

311:    Input Parameters:
312: +   dmmg - DMMG solve context
313: -   level - the number of the level you want the context for

315:    Level: intermediate

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

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

322: /*MC
323:    DMMGSetUser - Sets the user context for a particular level

325:    Synopsis:
326:    PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)

328:    Not Collective

330:    Input Parameters:
331: +   dmmg - DMMG solve context
332: .   level - the number of the level you want the context for
333: -   ctx - the context

335:    Level: intermediate

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

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

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

345: /*MC
346:    DMMGGetLevels - Gets the number of levels in a DMMG object

348:    Synopsis:
349:    PetscInt DMMGGetLevels(DMMG *dmmg)

351:    Not Collective

353:    Input Parameter:
354: .   dmmg - DMMG solve context

356:    Level: intermediate

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

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

363: /*MC
364:    DMMGGetDMMG - Returns the DMMG struct for the finest level

366:    Synopsis:
367:    DMMG DMMGGetDMMG(DMMG *dmmg)

369:    Not Collective

371:    Input Parameter:
372: .   dmmg - DMMG solve context

374:    Level: intermediate

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

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

381: #define PCDMMG      "pcdmmg"
382: EXTERN PetscErrorCode PCDMMGSetDMMG(PC,DMMG*);

385: #endif