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 petscdmda.h

 10: /*S
 11:      DMMGArray - Fortran only. This is used in the main program when doing DMMGCreate(), DMMGSetDM() etc.
 12:         in the subroutines like FormFunction() one should use DMMG.

 14:     This is being deprecated. Use KSPSetDM() for linear problems and SNESSetDM() for nonlinear problems. 
 15:     See src/ksp/ksp/examples/tutorials/ex45.c and src/snes/examples/tutorials/ex57.c 

 17:         You can use DMMGArrayGetDMMG(DMMGArray,DMMG,ierr) to obtain the DMMG from a DMMG.

 19:    Level: intermediate

 21:   Concepts: multigrid, Newton-multigrid

 23: .seealso:  DMCompositeCreate(),  DMComposite, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES(), DMMGSetInitialGuess(),
 24:            DMMGSetNullSpace(), DMMGSetMatType()
 25: S*/

 27: /*S
 28:      DMMG -  Data structure to easily manage multi-level non-linear solvers on grids managed by DM

 30:     This is being deprecated. Use KSPSetDM() for linear problems and SNESSetDM() for nonlinear problems. 
 31:     See src/ksp/ksp/examples/tutorials/ex45.c and src/snes/examples/tutorials/ex57.c 
 32:           
 33:    Level: intermediate

 35:    Fortran Users: see also DMMGArray

 37:   Concepts: multigrid, Newton-multigrid

 39: .seealso:  DMCompositeCreate(), DMComposite, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES(), DMMGSetInitialGuess(),
 40:            DMMGSetNullSpace(),  DMMGSetMatType()
 41: S*/
 42: typedef struct _n_DMMG* DMMG;
 43: struct _n_DMMG {
 44:   DM             dm;                   /* grid information for this level */
 45:   Vec            x,b,r;                /* global vectors used in multigrid preconditioner for this level*/
 46:   Mat            J;                    /* matrix on this level */
 47:   Mat            B;
 48:   Mat            R;                    /* restriction to next coarser level (not defined on level 0) */
 49:   PetscInt       nlevels;              /* number of levels above this one (total number of levels on level 0)*/
 50:   MPI_Comm       comm;
 51:   PetscErrorCode (*solve)(DMMG*,PetscInt);
 52:   void           *user;
 53:   PetscBool      galerkin;                  /* for A_c = R*A*R^T */
 54:   MatType        mtype;                     /* create matrices of this type */
 55:   char           *prefix;

 57:   /* KSP only */
 58:   KSP            ksp;
 59:   PetscErrorCode (*rhs)(DMMG,Vec);

 61:   /* SNES only */
 62:   Vec            Rscale;                 /* scaling to restriction before computing Jacobian */
 63:   PetscErrorCode (*computejacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);

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

 68:   PetscBool      getcoloringfrommat;     /* call a graph coloring algorithm on the matrix to get the coloring, instead of getting it from the DM */
 69:   ISColoringType isctype;
 70:   MatFDColoring  fdcoloring;             /* only used with FD coloring for Jacobian */
 71:   SNES           snes;
 72:   PetscErrorCode (*initialguess)(DMMG,Vec);
 73:   Vec            w,work1,work2;         /* global vectors */
 74:   Vec            lwork1;

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

 78:   /* FAS only */
 79:   NLF            nlf;                   /* FAS smoother object */
 80:   VecScatter     inject;                /* inject from this level to the next coarsest */
 81:   PetscBool      monitor,monitorall;
 82:   PetscInt       presmooth,postsmooth,coarsesmooth;
 83:   PetscReal      rtol,abstol,rrtol;       /* convergence tolerance */
 84: 
 85: };



110: #if defined(PETSC_HAVE_ADIC)
111: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) \
112:   DMMGSetSNESLocal_Private(dmmg,(DMDALocalFunction1)function,(DMDALocalFunction1)jacobian,(DMDALocalFunction1)(ad_function),(DMDALocalFunction1)(admf_function))
113: #else
114: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) DMMGSetSNESLocal_Private(dmmg,(DMDALocalFunction1)function,(DMDALocalFunction1)jacobian,(DMDALocalFunction1)0,(DMDALocalFunction1)0)
115: #endif

118: #if defined(PETSC_HAVE_ADIC)
119: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,void*,void*))(ad_function),(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,void*,void*))(admf_function))
120: #else
121: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
122: #endif

125: #if defined(PETSC_HAVE_ADIC)
126: #  define DMMGSetSNESLocalib(dmmg,function,ad_function,admf_function) DMMGSetSNESLocalib_Private(dmmg,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,void*,void*))(ad_function),(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,void*,void*))(admf_function))
127: #else
128: #  define DMMGSetSNESLocalib(dmmg,function,ad_function,admf_function) DMMGSetSNESLocalib_Private(dmmg,(PetscErrorCode(*)(DMDALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
129: #endif


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

136:    Synopsis:
137:    Vec DMMGGetRHS(DMMG *dmmg)

139:    Not Collective, but resulting vector is parallel

141:    Input Parameters:
142: .   dmmg - DMMG solve context

144:    Level: intermediate

146:    Fortran Usage:
147: .     DMMGGetRHS(DMMG dmmg,Vec b,PetscErrorCode ierr)

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

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

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

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

159:    Synopsis:
160:    Vec DMMGGetx(DMMG *dmmg)

162:    Not Collective, but resulting vector is parallel

164:    Input Parameters:
165: .   dmmg - DMMG solve context

167:    Level: intermediate

169:    Fortran Usage:
170: .     DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)

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

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

177: /*MC
178:    DMMGGetJ - Returns the Jacobian (matrix) for the finest level

180:    Synopsis:
181:    Mat DMMGGetJ(DMMG *dmmg)

183:    Not Collective

185:    Input Parameter:
186: .   dmmg - DMMG solve context

188:    Level: intermediate

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

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

195: /*MC
196:    DMMGGetComm - Returns the MPI_Comm for the finest level

198:    Synopsis:
199:    MPI_Comm DMMGGetJ(DMMG *dmmg)

201:    Not Collective

203:    Input Parameter:
204: .   dmmg - DMMG solve context

206:    Level: intermediate

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

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

213: /*MC
214:    DMMGGetB - Returns the matrix for the finest level used to construct the preconditioner; usually 
215:               the same as the Jacobian

217:    Synopsis:
218:    Mat DMMGGetJ(DMMG *dmmg)

220:    Not Collective

222:    Input Parameter:
223: .   dmmg - DMMG solve context

225:    Level: intermediate

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

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

232: /*MC
233:    DMMGGetFine - Returns the DMMG associated with the finest level

235:    Synopsis:
236:    DMMG DMMGGetFine(DMMG *dmmg)

238:    Not Collective

240:    Input Parameter:
241: .   dmmg - DMMG solve context

243:    Level: intermediate

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

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


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

254:    Synopsis:
255:    KSP DMMGGetKSP(DMMG *dmmg)

257:    Not Collective

259:    Input Parameter:
260: .   dmmg - DMMG solve context

262:    Level: intermediate

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

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

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

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

276:    Synopsis:
277:    SNES DMMGGetSNES(DMMG *dmmg)

279:    Not Collective

281:    Input Parameter:
282: .   dmmg - DMMG solve context

284:    Level: intermediate

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

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

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

293: /*MC
294:    DMMGGetDM - Gets the DM object on the finest level

296:    Synopsis:
297:    DM DMMGGetDM(DMMG *dmmg)

299:    Not Collective

301:    Input Parameter:
302: .   dmmg - DMMG solve context

304:    Level: intermediate

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

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

311: /*MC
312:    DMMGGetUser - Returns the user context for a particular level

314:    Synopsis:
315:    void* DMMGGetUser(DMMG *dmmg,PetscInt level)

317:    Not Collective

319:    Input Parameters:
320: +   dmmg - DMMG solve context
321: -   level - the number of the level you want the context for

323:    Level: intermediate

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

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

330: /*MC
331:    DMMGSetUser - Sets the user context for a particular level

333:    Synopsis:
334:    PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)

336:    Not Collective

338:    Input Parameters:
339: +   dmmg - DMMG solve context
340: .   level - the number of the level you want the context for
341: -   ctx - the context

343:    Level: intermediate

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

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

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

353: /*MC
354:    DMMGGetLevels - Gets the number of levels in a DMMG object

356:    Synopsis:
357:    PetscInt DMMGGetLevels(DMMG *dmmg)

359:    Not Collective

361:    Input Parameter:
362: .   dmmg - DMMG solve context

364:    Level: intermediate

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

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

372: #endif