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(), DMMGSetInitialGuess(),
 18:            DMMGSetNullSpace(), DMMGSetUseGalerkin(), DMMGSetMatType()
 19: S*/
 20: typedef struct _n_DMMG* DMMG;
 21: struct _n_DMMG {
 22:   DM             dm;                   /* grid information for this level */
 23:   Vec            x,b,r;                /* global vectors used in multigrid preconditioner for this level*/
 24:   Mat            J;                    /* matrix on this level */
 25:   Mat            B;
 26:   Mat            R;                    /* restriction to next coarser level (not defined on level 0) */
 27:   PetscInt       nlevels;              /* number of levels above this one (total number of levels on level 0)*/
 28:   MPI_Comm       comm;
 29:   PetscErrorCode (*solve)(DMMG*,PetscInt);
 30:   void           *user;
 31:   PetscTruth     galerkin;                  /* for A_c = R*A*R^T */
 32:   MatType        mtype;                     /* create matrices of this type */

 34:   /* KSP only */
 35:   KSP            ksp;
 36:   PetscErrorCode (*rhs)(DMMG,Vec);

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

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

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

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

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

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

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

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

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

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


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

108:    Synopsis:
109:    Vec DMMGGetRHS(DMMG *dmmg)

111:    Not Collective, but resulting vector is parallel

113:    Input Parameters:
114: .   dmmg - DMMG solve context

116:    Level: intermediate

118:    Fortran Usage:
119: .     DMMGGetRHS(DMMG dmmg,Vec b,PetscErrorCode ierr)

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

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

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

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

131:    Synopsis:
132:    Vec DMMGGetx(DMMG *dmmg)

134:    Not Collective, but resulting vector is parallel

136:    Input Parameters:
137: .   dmmg - DMMG solve context

139:    Level: intermediate

141:    Fortran Usage:
142: .     DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)

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

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

149: /*MC
150:    DMMGGetJ - Returns the Jacobian (matrix) for the finest level

152:    Synopsis:
153:    Mat DMMGGetJ(DMMG *dmmg)

155:    Not Collective

157:    Input Parameter:
158: .   dmmg - DMMG solve context

160:    Level: intermediate

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

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

167: /*MC
168:    DMMGGetComm - Returns the MPI_Comm for the finest level

170:    Synopsis:
171:    MPI_Comm DMMGGetJ(DMMG *dmmg)

173:    Not Collective

175:    Input Parameter:
176: .   dmmg - DMMG solve context

178:    Level: intermediate

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

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

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

189:    Synopsis:
190:    Mat DMMGGetJ(DMMG *dmmg)

192:    Not Collective

194:    Input Parameter:
195: .   dmmg - DMMG solve context

197:    Level: intermediate

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

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

204: /*MC
205:    DMMGGetFine - Returns the DMMG associated with the finest level

207:    Synopsis:
208:    DMMG DMMGGetFine(DMMG *dmmg)

210:    Not Collective

212:    Input Parameter:
213: .   dmmg - DMMG solve context

215:    Level: intermediate

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

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


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

226:    Synopsis:
227:    KSP DMMGGetKSP(DMMG *dmmg)

229:    Not Collective

231:    Input Parameter:
232: .   dmmg - DMMG solve context

234:    Level: intermediate

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

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

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

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

248:    Synopsis:
249:    SNES DMMGGetSNES(DMMG *dmmg)

251:    Not Collective

253:    Input Parameter:
254: .   dmmg - DMMG solve context

256:    Level: intermediate

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

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

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

265: /*MC
266:    DMMGGetDM - Gets the DM object on the finest level

268:    Synopsis:
269:    DM DMMGGetDM(DMMG *dmmg)

271:    Not Collective

273:    Input Parameter:
274: .   dmmg - DMMG solve context

276:    Level: intermediate

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

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

283: /*MC
284:    DMMGGetDA - Gets the DA object on the finest level

286:    Synopsis:
287:    DA DMMGGetDA(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(), DMMGGetVecPack()

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

303: /*MC
304:    DMMGGetVecPack - Gets the VecPack object on the finest level

306:    Synopsis:
307:    VecPack DMMGGetVecPack(DMMG *dmmg)

309:    Not Collective

311:    Input Parameter:
312: .   dmmg - DMMG solve context

314:    Level: intermediate

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

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

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

323: /*MC
324:    DMMGGetUser - Returns the user context for a particular level

326:    Synopsis:
327:    void* DMMGGetUser(DMMG *dmmg,PetscInt level)

329:    Not Collective

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

335:    Level: intermediate

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

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

342: /*MC
343:    DMMGSetUser - Sets the user context for a particular level

345:    Synopsis:
346:    PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)

348:    Not Collective

350:    Input Parameters:
351: +   dmmg - DMMG solve context
352: .   level - the number of the level you want the context for
353: -   ctx - the context

355:    Level: intermediate

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

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

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

365: /*MC
366:    DMMGGetLevels - Gets the number of levels in a DMMG object

368:    Synopsis:
369:    PetscInt DMMGGetLevels(DMMG *dmmg)

371:    Not Collective

373:    Input Parameter:
374: .   dmmg - DMMG solve context

376:    Level: intermediate

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

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

383: /*MC
384:    DMMGGetDMMG - Returns the DMMG struct for the finest level

386:    Synopsis:
387:    DMMG DMMGGetDMMG(DMMG *dmmg)

389:    Not Collective

391:    Input Parameter:
392: .   dmmg - DMMG solve context

394:    Level: intermediate

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

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

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

405: #endif