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:      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:         You can use DMMGArrayGetDMMG(DMMGArray,DMMG,ierr) to obtain the DMMG from a DMMG.

 16:    Level: intermediate

 18:   Concepts: multigrid, Newton-multigrid

 20: .seealso:  DMCompositeCreate(), DA, DMComposite, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES(), DMMGSetInitialGuess(),
 21:            DMMGSetNullSpace(), DMMGSetUseGalerkin(), DMMGSetMatType()
 22: S*/

 24: /*S
 25:      DMMG -  Data structure to easily manage multi-level non-linear solvers on grids managed by DM
 26:           
 27:    Level: intermediate

 29:    Fortran Users: see also DMMGArray

 31:   Concepts: multigrid, Newton-multigrid

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

 51:   /* KSP only */
 52:   KSP            ksp;
 53:   PetscErrorCode (*rhs)(DMMG,Vec);

 55:   /* SNES only */
 56:   Vec            Rscale;                 /* scaling to restriction before computing Jacobian */
 57:   PetscErrorCode (*computejacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
 58:   PetscErrorCode (*computefunction)(SNES,Vec,Vec,void*);

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

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

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

 73:   /* FAS only */
 74:   NLF            nlf;                   /* FAS smoother object */
 75:   VecScatter     inject;                /* inject from this level to the next coarsest */
 76:   PetscTruth     monitor,monitorall;
 77:   PetscInt       presmooth,postsmooth,coarsesmooth;
 78:   PetscReal      rtol,abstol,rrtol;       /* convergence tolerance */
 79: 
 80: };

 82: EXTERN PetscErrorCode  DMMGCreate(MPI_Comm,PetscInt,void*,DMMG**);
 83: EXTERN PetscErrorCode  DMMGDestroy(DMMG*);
 84: EXTERN PetscErrorCode  DMMGSetUp(DMMG*);
 85: EXTERN PetscErrorCode  DMMGSetKSP(DMMG*,PetscErrorCode (*)(DMMG,Vec),PetscErrorCode (*)(DMMG,Mat,Mat));
 86: EXTERN PetscErrorCode  DMMGSetSNES(DMMG*,PetscErrorCode (*)(SNES,Vec,Vec,void*),PetscErrorCode (*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
 87: EXTERN PetscErrorCode  DMMGSetFromOptions(DMMG*);

 89: EXTERN PetscErrorCode  DMMGSetInitialGuessLocal(DMMG*,PetscErrorCode (*)(void));
 90: EXTERN PetscErrorCode  DMMGSetInitialGuess(DMMG*,PetscErrorCode (*)(DMMG,Vec));
 91: EXTERN PetscErrorCode  DMMGInitialGuessCurrent(DMMG,Vec);
 92: EXTERN PetscErrorCode  DMMGView(DMMG*,PetscViewer);
 93: EXTERN PetscErrorCode  DMMGSolve(DMMG*);
 94: EXTERN PetscErrorCode  DMMGSetUseMatrixFree(DMMG*);
 95: EXTERN PetscErrorCode  DMMGSetDM(DMMG*,DM);
 96: EXTERN PetscErrorCode  DMMGSetUpLevel(DMMG*,KSP,PetscInt);
 97: EXTERN PetscErrorCode  DMMGSetUseGalerkinCoarse(DMMG*);
 98: EXTERN PetscErrorCode  DMMGSetNullSpace(DMMG*,PetscTruth,PetscInt,PetscErrorCode (*)(DMMG,Vec[]));
 99: EXTERN PetscErrorCode  DMMGSetMatType(DMMG*,const MatType);
100: EXTERN PetscErrorCode  DMMGSetISColoringType(DMMG*,ISColoringType);
101: EXTERN PetscErrorCode  DMMGSetOptionsPrefix(DMMG*,const char[]);
102: EXTERN PetscErrorCode  DMMGFormFunction(SNES,Vec,Vec,void *);

104: EXTERN PetscErrorCode  DMMGGetSNESLocal(DMMG*,DALocalFunction1*,DALocalFunction1*);
105: EXTERN PetscErrorCode  DMMGSetSNESLocal_Private(DMMG*,DALocalFunction1,DALocalFunction1,DALocalFunction1,DALocalFunction1);
106: #if defined(PETSC_HAVE_ADIC)
107: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) \
108:   DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)(ad_function),(DALocalFunction1)(admf_function))
109: #else
110: #  define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)0,(DALocalFunction1)0)
111: #endif

113: EXTERN PetscErrorCode  DMMGSetSNESLocali_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
114: #if defined(PETSC_HAVE_ADIC)
115: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocal,i_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))
116: #else
117: #  define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
118: #endif

120: EXTERN PetscErrorCode  DMMGSetSNESLocalib_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
121: #if defined(PETSC_HAVE_ADIC)
122: #  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))
123: #else
124: #  define DMMGSetSNESLocalib(dmmg,function,ad_function,admf_function) DMMGSetSNESLocalib_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
125: #endif


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

132:    Synopsis:
133:    Vec DMMGGetRHS(DMMG *dmmg)

135:    Not Collective, but resulting vector is parallel

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

140:    Level: intermediate

142:    Fortran Usage:
143: .     DMMGGetRHS(DMMG dmmg,Vec b,PetscErrorCode ierr)

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

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

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

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

155:    Synopsis:
156:    Vec DMMGGetx(DMMG *dmmg)

158:    Not Collective, but resulting vector is parallel

160:    Input Parameters:
161: .   dmmg - DMMG solve context

163:    Level: intermediate

165:    Fortran Usage:
166: .     DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)

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

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

173: /*MC
174:    DMMGGetJ - Returns the Jacobian (matrix) for the finest level

176:    Synopsis:
177:    Mat DMMGGetJ(DMMG *dmmg)

179:    Not Collective

181:    Input Parameter:
182: .   dmmg - DMMG solve context

184:    Level: intermediate

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

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

191: /*MC
192:    DMMGGetComm - Returns the MPI_Comm for the finest level

194:    Synopsis:
195:    MPI_Comm DMMGGetJ(DMMG *dmmg)

197:    Not Collective

199:    Input Parameter:
200: .   dmmg - DMMG solve context

202:    Level: intermediate

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

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

209: /*MC
210:    DMMGGetB - Returns the matrix for the finest level used to construct the preconditioner; usually 
211:               the same as the Jacobian

213:    Synopsis:
214:    Mat DMMGGetJ(DMMG *dmmg)

216:    Not Collective

218:    Input Parameter:
219: .   dmmg - DMMG solve context

221:    Level: intermediate

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

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

228: /*MC
229:    DMMGGetFine - Returns the DMMG associated with the finest level

231:    Synopsis:
232:    DMMG DMMGGetFine(DMMG *dmmg)

234:    Not Collective

236:    Input Parameter:
237: .   dmmg - DMMG solve context

239:    Level: intermediate

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

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


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

250:    Synopsis:
251:    KSP DMMGGetKSP(DMMG *dmmg)

253:    Not Collective

255:    Input Parameter:
256: .   dmmg - DMMG solve context

258:    Level: intermediate

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

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

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

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

272:    Synopsis:
273:    SNES DMMGGetSNES(DMMG *dmmg)

275:    Not Collective

277:    Input Parameter:
278: .   dmmg - DMMG solve context

280:    Level: intermediate

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

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

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

289: /*MC
290:    DMMGGetDM - Gets the DM object on the finest level

292:    Synopsis:
293:    DM DMMGGetDM(DMMG *dmmg)

295:    Not Collective

297:    Input Parameter:
298: .   dmmg - DMMG solve context

300:    Level: intermediate

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

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

307: /*MC
308:    DMMGGetDA - Gets the DA object on the finest level

310:    Synopsis:
311:    DA DMMGGetDA(DMMG *dmmg)

313:    Not Collective

315:    Input Parameter:
316: .   dmmg - DMMG solve context

318:    Level: intermediate

320:    Notes: Use only if the DMMG was created with a DA, not a DMComposite

322: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP(), DMMGGetDMComposite()

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

327: /*MC
328:    DMMGGetDMComposite - Gets the DMComposite object on the finest level

330:    Synopsis:
331:    DMComposite DMMGGetDMComposite(DMMG *dmmg)

333:    Not Collective

335:    Input Parameter:
336: .   dmmg - DMMG solve context

338:    Level: intermediate

340:    Notes: Use only if the DMMG was created with a DA, not a DMComposite

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

344: M*/
345: #define DMMGGetDMComposite(ctx)        (DMComposite)((ctx)[(ctx)[0]->nlevels-1]->dm)

347: /*MC
348:    DMMGGetUser - Returns the user context for a particular level

350:    Synopsis:
351:    void* DMMGGetUser(DMMG *dmmg,PetscInt level)

353:    Not Collective

355:    Input Parameters:
356: +   dmmg - DMMG solve context
357: -   level - the number of the level you want the context for

359:    Level: intermediate

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

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

366: /*MC
367:    DMMGSetUser - Sets the user context for a particular level

369:    Synopsis:
370:    PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)

372:    Not Collective

374:    Input Parameters:
375: +   dmmg - DMMG solve context
376: .   level - the number of the level you want the context for
377: -   ctx - the context

379:    Level: intermediate

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

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

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

389: /*MC
390:    DMMGGetLevels - Gets the number of levels in a DMMG object

392:    Synopsis:
393:    PetscInt DMMGGetLevels(DMMG *dmmg)

395:    Not Collective

397:    Input Parameter:
398: .   dmmg - DMMG solve context

400:    Level: intermediate

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

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

407: /*MC
408:    DMMGGetDMMG - Returns the DMMG struct for the finest level

410:    Synopsis:
411:    DMMG DMMGGetDMMG(DMMG *dmmg)

413:    Not Collective

415:    Input Parameter:
416: .   dmmg - DMMG solve context

418:    Level: intermediate

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

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

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

429: #endif