Actual source code: mg.c

  2: /*
  3:     Defines the multigrid preconditioner interface.
  4: */
  5: #include <../src/ksp/pc/impls/mg/mgimpl.h>                    /*I "petscpcmg.h" I*/


 10: PetscErrorCode PCMGMCycle_Private(PC pc,PC_MG_Levels **mglevelsin,PCRichardsonConvergedReason *reason)
 11: {
 12:   PC_MG          *mg = (PC_MG*)pc->data;
 13:   PC_MG_Levels   *mgc,*mglevels = *mglevelsin;
 15:   PetscInt       cycles = (mglevels->level == 1) ? 1 : (PetscInt) mglevels->cycles;


 19:   if (mglevels->eventsmoothsolve) {PetscLogEventBegin(mglevels->eventsmoothsolve,0,0,0,0);}
 20:   KSPSolve(mglevels->smoothd,mglevels->b,mglevels->x);  /* pre-smooth */
 21:   if (mglevels->eventsmoothsolve) {PetscLogEventEnd(mglevels->eventsmoothsolve,0,0,0,0);}
 22:   if (mglevels->level) {  /* not the coarsest grid */
 23:     if (mglevels->eventresidual) {PetscLogEventBegin(mglevels->eventresidual,0,0,0,0);}
 24:     (*mglevels->residual)(mglevels->A,mglevels->b,mglevels->x,mglevels->r);
 25:     if (mglevels->eventresidual) {PetscLogEventEnd(mglevels->eventresidual,0,0,0,0);}

 27:     /* if on finest level and have convergence criteria set */
 28:     if (mglevels->level == mglevels->levels-1 && mg->ttol && reason) {
 29:       PetscReal rnorm;
 30:       VecNorm(mglevels->r,NORM_2,&rnorm);
 31:       if (rnorm <= mg->ttol) {
 32:         if (rnorm < mg->abstol) {
 33:           *reason = PCRICHARDSON_CONVERGED_ATOL;
 34:           PetscInfo2(pc,"Linear solver has converged. Residual norm %G is less than absolute tolerance %G\n",rnorm,mg->abstol);
 35:         } else {
 36:           *reason = PCRICHARDSON_CONVERGED_RTOL;
 37:           PetscInfo2(pc,"Linear solver has converged. Residual norm %G is less than relative tolerance times initial residual norm %G\n",rnorm,mg->ttol);
 38:         }
 39:         return(0);
 40:       }
 41:     }

 43:     mgc = *(mglevelsin - 1);
 44:     if (mglevels->eventinterprestrict) {PetscLogEventBegin(mglevels->eventinterprestrict,0,0,0,0);}
 45:     MatRestrict(mglevels->restrct,mglevels->r,mgc->b);
 46:     if (mglevels->eventinterprestrict) {PetscLogEventEnd(mglevels->eventinterprestrict,0,0,0,0);}
 47:     VecSet(mgc->x,0.0);
 48:     while (cycles--) {
 49:       PCMGMCycle_Private(pc,mglevelsin-1,reason);
 50:     }
 51:     if (mglevels->eventinterprestrict) {PetscLogEventBegin(mglevels->eventinterprestrict,0,0,0,0);}
 52:     MatInterpolateAdd(mglevels->interpolate,mgc->x,mglevels->x,mglevels->x);
 53:     if (mglevels->eventinterprestrict) {PetscLogEventEnd(mglevels->eventinterprestrict,0,0,0,0);}
 54:     if (mglevels->eventsmoothsolve) {PetscLogEventBegin(mglevels->eventsmoothsolve,0,0,0,0);}
 55:     KSPSolve(mglevels->smoothu,mglevels->b,mglevels->x);    /* post smooth */
 56:     if (mglevels->eventsmoothsolve) {PetscLogEventEnd(mglevels->eventsmoothsolve,0,0,0,0);}
 57:   }
 58:   return(0);
 59: }

 63: static PetscErrorCode PCApplyRichardson_MG(PC pc,Vec b,Vec x,Vec w,PetscReal rtol,PetscReal abstol, PetscReal dtol,PetscInt its,PetscBool  zeroguess,PetscInt *outits,PCRichardsonConvergedReason *reason)
 64: {
 65:   PC_MG          *mg = (PC_MG*)pc->data;
 66:   PC_MG_Levels   **mglevels = mg->levels;
 68:   PetscInt       levels = mglevels[0]->levels,i;

 71:   mglevels[levels-1]->b    = b;
 72:   mglevels[levels-1]->x    = x;

 74:   mg->rtol = rtol;
 75:   mg->abstol = abstol;
 76:   mg->dtol = dtol;
 77:   if (rtol) {
 78:     /* compute initial residual norm for relative convergence test */
 79:     PetscReal rnorm;
 80:     if (zeroguess) {
 81:       VecNorm(b,NORM_2,&rnorm);
 82:     } else {
 83:       (*mglevels[levels-1]->residual)(mglevels[levels-1]->A,b,x,w);
 84:       VecNorm(w,NORM_2,&rnorm);
 85:     }
 86:     mg->ttol = PetscMax(rtol*rnorm,abstol);
 87:   } else if (abstol) {
 88:     mg->ttol = abstol;
 89:   } else {
 90:     mg->ttol = 0.0;
 91:   }

 93:   /* since smoother is applied to full system, not just residual we need to make sure that smoothers don't 
 94:      stop prematurely do to small residual */
 95:   for (i=1; i<levels; i++) {
 96:     KSPSetTolerances(mglevels[i]->smoothu,0,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT);
 97:     if (mglevels[i]->smoothu != mglevels[i]->smoothd) {
 98:       KSPSetTolerances(mglevels[i]->smoothd,0,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT);
 99:     }
100:   }

102:   *reason = (PCRichardsonConvergedReason)0;
103:   for (i=0; i<its; i++) {
104:     PCMGMCycle_Private(pc,mglevels+levels-1,reason);
105:     if (*reason) break;
106:   }
107:   if (!*reason) *reason = PCRICHARDSON_CONVERGED_ITS;
108:   *outits = i;
109:   return(0);
110: }

114: PetscErrorCode PCReset_MG(PC pc)
115: {
116:   PC_MG          *mg = (PC_MG*)pc->data;
117:   PC_MG_Levels   **mglevels = mg->levels;
119:   PetscInt       i,n;

122:   if (mglevels) {
123:     n = mglevels[0]->levels;
124:     for (i=0; i<n-1; i++) {
125:       VecDestroy(&mglevels[i+1]->r);
126:       VecDestroy(&mglevels[i]->b);
127:       VecDestroy(&mglevels[i]->x);
128:       MatDestroy(&mglevels[i+1]->restrct);
129:       MatDestroy(&mglevels[i+1]->interpolate);
130:       VecDestroy(&mglevels[i+1]->rscale);
131:     }

133:     for (i=0; i<n; i++) {
134:       MatDestroy(&mglevels[i]->A);
135:       if (mglevels[i]->smoothd != mglevels[i]->smoothu) {
136:         KSPReset(mglevels[i]->smoothd);
137:       }
138:       KSPReset(mglevels[i]->smoothu);
139:     }
140:   }
141:   return(0);
142: }

146: /*@C
147:    PCMGSetLevels - Sets the number of levels to use with MG.
148:    Must be called before any other MG routine.

150:    Logically Collective on PC

152:    Input Parameters:
153: +  pc - the preconditioner context
154: .  levels - the number of levels
155: -  comms - optional communicators for each level; this is to allow solving the coarser problems
156:            on smaller sets of processors. Use PETSC_NULL_OBJECT for default in Fortran

158:    Level: intermediate

160:    Notes:
161:      If the number of levels is one then the multigrid uses the -mg_levels prefix
162:   for setting the level options rather than the -mg_coarse prefix.

164: .keywords: MG, set, levels, multigrid

166: .seealso: PCMGSetType(), PCMGGetLevels()
167: @*/
168: PetscErrorCode  PCMGSetLevels(PC pc,PetscInt levels,MPI_Comm *comms)
169: {
171:   PC_MG          *mg = (PC_MG*)pc->data;
172:   MPI_Comm       comm = ((PetscObject)pc)->comm;
173:   PC_MG_Levels   **mglevels = mg->levels;
174:   PetscInt       i;
175:   PetscMPIInt    size;
176:   const char     *prefix;
177:   PC             ipc;
178:   PetscInt       n;

183:   if (mg->nlevels == levels) return(0);
184:   if (mglevels) {
185:     /* changing the number of levels so free up the previous stuff */
186:     PCReset_MG(pc);
187:     n = mglevels[0]->levels;
188:     for (i=0; i<n; i++) {
189:       if (mglevels[i]->smoothd != mglevels[i]->smoothu) {
190:         KSPDestroy(&mglevels[i]->smoothd);
191:       }
192:       KSPDestroy(&mglevels[i]->smoothu);
193:       PetscFree(mglevels[i]);
194:     }
195:     PetscFree(mg->levels);
196:   }

198:   mg->nlevels      = levels;

200:   PetscMalloc(levels*sizeof(PC_MG*),&mglevels);
201:   PetscLogObjectMemory(pc,levels*(sizeof(PC_MG*)));

203:   PCGetOptionsPrefix(pc,&prefix);

205:   for (i=0; i<levels; i++) {
206:     PetscNewLog(pc,PC_MG_Levels,&mglevels[i]);
207:     mglevels[i]->level           = i;
208:     mglevels[i]->levels          = levels;
209:     mglevels[i]->cycles          = PC_MG_CYCLE_V;
210:     mg->default_smoothu = 1;
211:     mg->default_smoothd = 1;
212:     mglevels[i]->eventsmoothsetup    = 0;
213:     mglevels[i]->eventsmoothsolve    = 0;
214:     mglevels[i]->eventresidual       = 0;
215:     mglevels[i]->eventinterprestrict = 0;

217:     if (comms) comm = comms[i];
218:     KSPCreate(comm,&mglevels[i]->smoothd);
219:     PetscObjectIncrementTabLevel((PetscObject)mglevels[i]->smoothd,(PetscObject)pc,levels-i);
220:     KSPSetTolerances(mglevels[i]->smoothd,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT, mg->default_smoothd);
221:     KSPSetOptionsPrefix(mglevels[i]->smoothd,prefix);

223:     /* do special stuff for coarse grid */
224:     if (!i && levels > 1) {
225:       KSPAppendOptionsPrefix(mglevels[0]->smoothd,"mg_coarse_");

227:       /* coarse solve is (redundant) LU by default */
228:       KSPSetType(mglevels[0]->smoothd,KSPPREONLY);
229:       KSPGetPC(mglevels[0]->smoothd,&ipc);
230:       MPI_Comm_size(comm,&size);
231:       if (size > 1) {
232:         PCSetType(ipc,PCREDUNDANT);
233:       } else {
234:         PCSetType(ipc,PCLU);
235:       }

237:     } else {
238:       char tprefix[128];
239:       sprintf(tprefix,"mg_levels_%d_",(int)i);
240:       KSPAppendOptionsPrefix(mglevels[i]->smoothd,tprefix);
241:     }
242:     PetscLogObjectParent(pc,mglevels[i]->smoothd);
243:     mglevels[i]->smoothu    = mglevels[i]->smoothd;
244:     mg->rtol                = 0.0;
245:     mg->abstol              = 0.0;
246:     mg->dtol                = 0.0;
247:     mg->ttol                = 0.0;
248:     mg->cyclesperpcapply    = 1;
249:   }
250:   mg->am          = PC_MG_MULTIPLICATIVE;
251:   mg->levels      = mglevels;
252:   pc->ops->applyrichardson = PCApplyRichardson_MG;
253:   return(0);
254: }


259: PetscErrorCode PCDestroy_MG(PC pc)
260: {
262:   PC_MG          *mg = (PC_MG*)pc->data;
263:   PC_MG_Levels   **mglevels = mg->levels;
264:   PetscInt       i,n;

267:   PCReset_MG(pc);
268:   if (mglevels) {
269:     n = mglevels[0]->levels;
270:     for (i=0; i<n; i++) {
271:       if (mglevels[i]->smoothd != mglevels[i]->smoothu) {
272:         KSPDestroy(&mglevels[i]->smoothd);
273:       }
274:       KSPDestroy(&mglevels[i]->smoothu);
275:       PetscFree(mglevels[i]);
276:     }
277:     PetscFree(mg->levels);
278:   }
279:   PetscFree(pc->data);
280:   return(0);
281: }




289: /*
290:    PCApply_MG - Runs either an additive, multiplicative, Kaskadic
291:              or full cycle of multigrid. 

293:   Note: 
294:   A simple wrapper which calls PCMGMCycle(),PCMGACycle(), or PCMGFCycle(). 
295: */
298: static PetscErrorCode PCApply_MG(PC pc,Vec b,Vec x)
299: {
300:   PC_MG          *mg = (PC_MG*)pc->data;
301:   PC_MG_Levels   **mglevels = mg->levels;
303:   PetscInt       levels = mglevels[0]->levels,i;


307:   /* When the DM is supplying the matrix then it will not exist until here */
308:   for (i=0; i<levels; i++) {
309:     if (!mglevels[i]->A) {
310:       KSPGetOperators(mglevels[i]->smoothu,&mglevels[i]->A,PETSC_NULL,PETSC_NULL);
311:       PetscObjectReference((PetscObject)mglevels[i]->A);
312:     }
313:   }

315:   mglevels[levels-1]->b = b;
316:   mglevels[levels-1]->x = x;
317:   if (mg->am == PC_MG_MULTIPLICATIVE) {
318:     VecSet(x,0.0);
319:     for (i=0; i<mg->cyclesperpcapply; i++) {
320:       PCMGMCycle_Private(pc,mglevels+levels-1,PETSC_NULL);
321:     }
322:   }
323:   else if (mg->am == PC_MG_ADDITIVE) {
324:     PCMGACycle_Private(pc,mglevels);
325:   }
326:   else if (mg->am == PC_MG_KASKADE) {
327:     PCMGKCycle_Private(pc,mglevels);
328:   }
329:   else {
330:     PCMGFCycle_Private(pc,mglevels);
331:   }
332:   return(0);
333: }


338: PetscErrorCode PCSetFromOptions_MG(PC pc)
339: {
341:   PetscInt       m,levels = 1,cycles;
342:   PetscBool      flg,set;
343:   PC_MG          *mg = (PC_MG*)pc->data;
344:   PC_MG_Levels   **mglevels = mg->levels;
345:   PCMGType       mgtype;
346:   PCMGCycleType  mgctype;

349:   PetscOptionsHead("Multigrid options");
350:     if (!mg->levels) {
351:       PetscOptionsInt("-pc_mg_levels","Number of Levels","PCMGSetLevels",levels,&levels,&flg);
352:       if (!flg && pc->dm) {
353:         DMGetRefineLevel(pc->dm,&levels);
354:         levels++;
355:         mg->usedmfornumberoflevels = PETSC_TRUE;
356:       }
357:       PCMGSetLevels(pc,levels,PETSC_NULL);
358:     }
359:     mglevels = mg->levels;

361:     mgctype = (PCMGCycleType) mglevels[0]->cycles;
362:     PetscOptionsEnum("-pc_mg_cycle_type","V cycle or for W-cycle","PCMGSetCycleType",PCMGCycleTypes,(PetscEnum)mgctype,(PetscEnum*)&mgctype,&flg);
363:     if (flg) {
364:       PCMGSetCycleType(pc,mgctype);
365:     };
366:     flg  = PETSC_FALSE;
367:     PetscOptionsBool("-pc_mg_galerkin","Use Galerkin process to compute coarser operators","PCMGSetGalerkin",flg,&flg,&set);
368:     if (set) {
369:       PCMGSetGalerkin(pc,flg);
370:     }
371:     PetscOptionsInt("-pc_mg_smoothup","Number of post-smoothing steps","PCMGSetNumberSmoothUp",1,&m,&flg);
372:     if (flg) {
373:       PCMGSetNumberSmoothUp(pc,m);
374:     }
375:     PetscOptionsInt("-pc_mg_smoothdown","Number of pre-smoothing steps","PCMGSetNumberSmoothDown",1,&m,&flg);
376:     if (flg) {
377:       PCMGSetNumberSmoothDown(pc,m);
378:     }
379:     mgtype = mg->am;
380:     PetscOptionsEnum("-pc_mg_type","Multigrid type","PCMGSetType",PCMGTypes,(PetscEnum)mgtype,(PetscEnum*)&mgtype,&flg);
381:     if (flg) {
382:       PCMGSetType(pc,mgtype);
383:     }
384:     if (mg->am == PC_MG_MULTIPLICATIVE) {
385:       PetscOptionsInt("-pc_mg_multiplicative_cycles","Number of cycles for each preconditioner step","PCMGSetLevels",mg->cyclesperpcapply,&cycles,&flg);
386:       if (flg) {
387:         PCMGMultiplicativeSetCycles(pc,cycles);
388:       }
389:     }
390:     flg  = PETSC_FALSE;
391:     PetscOptionsBool("-pc_mg_log","Log times for each multigrid level","None",flg,&flg,PETSC_NULL);
392:     if (flg) {
393:       PetscInt i;
394:       char     eventname[128];
395:       if (!mglevels) SETERRQ(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
396:       levels = mglevels[0]->levels;
397:       for (i=0; i<levels; i++) {
398:         sprintf(eventname,"MGSetup Level %d",(int)i);
399:         PetscLogEventRegister(eventname,((PetscObject)pc)->classid,&mglevels[i]->eventsmoothsetup);
400:         sprintf(eventname,"MGSmooth Level %d",(int)i);
401:         PetscLogEventRegister(eventname,((PetscObject)pc)->classid,&mglevels[i]->eventsmoothsolve);
402:         if (i) {
403:           sprintf(eventname,"MGResid Level %d",(int)i);
404:           PetscLogEventRegister(eventname,((PetscObject)pc)->classid,&mglevels[i]->eventresidual);
405:           sprintf(eventname,"MGInterp Level %d",(int)i);
406:           PetscLogEventRegister(eventname,((PetscObject)pc)->classid,&mglevels[i]->eventinterprestrict);
407:         }
408:       }
409:     }
410:   PetscOptionsTail();
411:   return(0);
412: }

414: const char *PCMGTypes[] = {"MULTIPLICATIVE","ADDITIVE","FULL","KASKADE","PCMGType","PC_MG",0};
415: const char *PCMGCycleTypes[] = {"invalid","v","w","PCMGCycleType","PC_MG_CYCLE",0};

419: PetscErrorCode PCView_MG(PC pc,PetscViewer viewer)
420: {
421:   PC_MG          *mg = (PC_MG*)pc->data;
422:   PC_MG_Levels   **mglevels = mg->levels;
424:   PetscInt       levels = mglevels[0]->levels,i;
425:   PetscBool      iascii;

428:   PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
429:   if (iascii) {
430:     PetscViewerASCIIPrintf(viewer,"  MG: type is %s, levels=%D cycles=%s\n", PCMGTypes[mg->am],levels,(mglevels[0]->cycles == PC_MG_CYCLE_V) ? "v" : "w");
431:     if (mg->am == PC_MG_MULTIPLICATIVE) {
432:       PetscViewerASCIIPrintf(viewer,"    Cycles per PCApply=%d\n",mg->cyclesperpcapply);
433:     }
434:     if (mg->galerkin) {
435:       PetscViewerASCIIPrintf(viewer,"    Using Galerkin computed coarse grid matrices\n");
436:     } else {
437:       PetscViewerASCIIPrintf(viewer,"    Not using Galerkin computed coarse grid matrices\n");
438:     }
439:     for (i=0; i<levels; i++) {
440:       if (!i) {
441:         PetscViewerASCIIPrintf(viewer,"Coarse grid solver -- level -------------------------------\n",i);
442:       } else {
443:         PetscViewerASCIIPrintf(viewer,"Down solver (pre-smoother) on level %D -------------------------------\n",i);
444:       }
445:       PetscViewerASCIIPushTab(viewer);
446:       KSPView(mglevels[i]->smoothd,viewer);
447:       PetscViewerASCIIPopTab(viewer);
448:       if (i && mglevels[i]->smoothd == mglevels[i]->smoothu) {
449:         PetscViewerASCIIPrintf(viewer,"Up solver (post-smoother) same as down solver (pre-smoother)\n");
450:       } else if (i){
451:         PetscViewerASCIIPrintf(viewer,"Up solver (post-smoother) on level %D -------------------------------\n",i);
452:         PetscViewerASCIIPushTab(viewer);
453:         KSPView(mglevels[i]->smoothu,viewer);
454:         PetscViewerASCIIPopTab(viewer);
455:       }
456:     }
457:   } else SETERRQ1(((PetscObject)pc)->comm,PETSC_ERR_SUP,"Viewer type %s not supported for PCMG",((PetscObject)viewer)->type_name);
458:   return(0);
459: }

461: #include <private/dmimpl.h>
462: #include <private/kspimpl.h>

464: /*
465:     Calls setup for the KSP on each level
466: */
469: PetscErrorCode PCSetUp_MG(PC pc)
470: {
471:   PC_MG                   *mg = (PC_MG*)pc->data;
472:   PC_MG_Levels            **mglevels = mg->levels;
473:   PetscErrorCode          ierr;
474:   PetscInt                i,n = mglevels[0]->levels;
475:   PC                      cpc,mpc;
476:   PetscBool               preonly,lu,redundant,cholesky,svd,dump = PETSC_FALSE,opsset;
477:   Mat                     dA,dB;
478:   MatStructure            uflag;
479:   Vec                     tvec;
480:   DM                      *dms;
481:   PetscViewer             viewer = 0;

484:   if (mg->usedmfornumberoflevels) {
485:     PetscInt levels;
486:     DMGetRefineLevel(pc->dm,&levels);
487:     levels++;
488:     if (levels > n) { /* the problem is now being solved on a finer grid */
489:       PCMGSetLevels(pc,levels,PETSC_NULL);
490:       n    = levels;
491:       PCSetFromOptions(pc);  /* it is bad to call this here, but otherwise will never be called for the new hierarchy */
492:       mglevels =  mg->levels;
493:     }
494:   }


497:   /* If user did not provide fine grid operators OR operator was not updated since last global KSPSetOperators() */
498:   /* so use those from global PC */
499:   /* Is this what we always want? What if user wants to keep old one? */
500:   KSPGetOperatorsSet(mglevels[n-1]->smoothd,PETSC_NULL,&opsset);
501:   KSPGetPC(mglevels[0]->smoothd,&cpc);
502:   KSPGetPC(mglevels[n-1]->smoothd,&mpc);
503:   if (!opsset || ((cpc->setupcalled == 1) && (mpc->setupcalled == 2)) || ((mpc == cpc) && (mpc->setupcalled == 2))) {
504:     PetscInfo(pc,"Using outer operators to define finest grid operator \n  because PCMGGetSmoother(pc,nlevels-1,&ksp);KSPSetOperators(ksp,...); was not called.\n");
505:     KSPSetOperators(mglevels[n-1]->smoothd,pc->mat,pc->pmat,pc->flag);
506:   }

508:   if (pc->dm && !pc->setupcalled) {
509:     /* construct the interpolation from the DMs */
510:     Mat p;
511:     Vec rscale;
512:     PetscMalloc(n*sizeof(DM),&dms);
513:     dms[n-1] = pc->dm;
514:     for (i=n-2; i>-1; i--) {
515:       DMCoarsen(dms[i+1],PETSC_NULL,&dms[i]);
516:       KSPSetDM(mglevels[i]->smoothd,dms[i]);
517:       if (mg->galerkin) {KSPSetDMActive(mglevels[i]->smoothd,PETSC_FALSE);}
518:       DMSetFunction(dms[i],0);
519:       DMSetInitialGuess(dms[i],0);
520:       if (!mglevels[i+1]->interpolate) {
521:         DMGetInterpolation(dms[i],dms[i+1],&p,&rscale);
522:         PCMGSetInterpolation(pc,i+1,p);
523:         if (rscale) {PCMGSetRScale(pc,i+1,rscale);}
524:         VecDestroy(&rscale);
525:         MatDestroy(&p);
526:       }
527:     }

529:     for (i=n-2; i>-1; i--) {
530:       DMDestroy(&dms[i]);
531:     }
532:     PetscFree(dms);

534:     /* finest smoother also gets DM but it is not active */
535:     KSPSetDM(mglevels[n-1]->smoothd,pc->dm);
536:     KSPSetDMActive(mglevels[n-1]->smoothd,PETSC_FALSE);
537:   }

539:   if (mg->galerkin == 1) {
540:     Mat B;
541:     /* currently only handle case where mat and pmat are the same on coarser levels */
542:     KSPGetOperators(mglevels[n-1]->smoothd,&dA,&dB,&uflag);
543:     if (!pc->setupcalled) {
544:       for (i=n-2; i>-1; i--) {
545:         MatPtAP(dB,mglevels[i+1]->interpolate,MAT_INITIAL_MATRIX,1.0,&B);
546:         KSPSetOperators(mglevels[i]->smoothd,B,B,uflag);
547:         if (i != n-2) {PetscObjectDereference((PetscObject)dB);}
548:         dB   = B;
549:       }
550:       if (n > 1) {PetscObjectDereference((PetscObject)dB);}
551:     } else {
552:       for (i=n-2; i>-1; i--) {
553:         KSPGetOperators(mglevels[i]->smoothd,PETSC_NULL,&B,PETSC_NULL);
554:         MatPtAP(dB,mglevels[i+1]->interpolate,MAT_REUSE_MATRIX,1.0,&B);
555:         KSPSetOperators(mglevels[i]->smoothd,B,B,uflag);
556:         dB   = B;
557:       }
558:     }
559:   } else if (pc->dm && pc->dm->x) {
560:     /* need to restrict Jacobian location to coarser meshes for evaluation */
561:     for (i=n-2;i>-1; i--) {
562:       if (!mglevels[i]->smoothd->dm->x) {
563:         Vec *vecs;
564:         KSPGetVecs(mglevels[i]->smoothd,1,&vecs,0,PETSC_NULL);
565:         mglevels[i]->smoothd->dm->x = vecs[0];
566:         PetscFree(vecs);
567:       }
568:       MatRestrict(mglevels[i+1]->interpolate,mglevels[i+1]->smoothd->dm->x,mglevels[i]->smoothd->dm->x);
569:       VecPointwiseMult(mglevels[i]->smoothd->dm->x,mglevels[i]->smoothd->dm->x,mglevels[i+1]->rscale);
570:     }
571:   }

573:   if (!pc->setupcalled) {
574:     for (i=0; i<n; i++) {
575:       KSPSetFromOptions(mglevels[i]->smoothd);
576:     }
577:     for (i=1; i<n; i++) {
578:       if (mglevels[i]->smoothu && (mglevels[i]->smoothu != mglevels[i]->smoothd)) {
579:         KSPSetFromOptions(mglevels[i]->smoothu);
580:       }
581:     }
582:     for (i=1; i<n; i++) {
583:       if (mglevels[i]->restrct && !mglevels[i]->interpolate) {
584:         PCMGSetInterpolation(pc,i,mglevels[i]->restrct);
585:       }
586:       if (!mglevels[i]->restrct && mglevels[i]->interpolate) {
587:         PCMGSetRestriction(pc,i,mglevels[i]->interpolate);
588:       }
589: #if defined(PETSC_USE_DEBUG)
590:       if (!mglevels[i]->restrct || !mglevels[i]->interpolate) {
591:         SETERRQ1(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Need to set restriction or interpolation on level %d",(int)i);
592:       }
593: #endif
594:     }
595:     for (i=0; i<n-1; i++) {
596:       if (!mglevels[i]->b) {
597:         Vec *vec;
598:         KSPGetVecs(mglevels[i]->smoothd,1,&vec,0,PETSC_NULL);
599:         PCMGSetRhs(pc,i,*vec);
600:         VecDestroy(vec);
601:         PetscFree(vec);
602:       }
603:       if (!mglevels[i]->r && i) {
604:         VecDuplicate(mglevels[i]->b,&tvec);
605:         PCMGSetR(pc,i,tvec);
606:         VecDestroy(&tvec);
607:       }
608:       if (!mglevels[i]->x) {
609:         VecDuplicate(mglevels[i]->b,&tvec);
610:         PCMGSetX(pc,i,tvec);
611:         VecDestroy(&tvec);
612:       }
613:     }
614:     if (n != 1 && !mglevels[n-1]->r) {
615:       /* PCMGSetR() on the finest level if user did not supply it */
616:       Vec *vec;
617:       KSPGetVecs(mglevels[n-1]->smoothd,1,&vec,0,PETSC_NULL);
618:       PCMGSetR(pc,n-1,*vec);
619:       VecDestroy(vec);
620:       PetscFree(vec);
621:     }
622:   }


625:   for (i=1; i<n; i++) {
626:     if (mglevels[i]->smoothu == mglevels[i]->smoothd) {
627:       /* if doing only down then initial guess is zero */
628:       KSPSetInitialGuessNonzero(mglevels[i]->smoothd,PETSC_TRUE);
629:     }
630:     if (mglevels[i]->eventsmoothsetup) {PetscLogEventBegin(mglevels[i]->eventsmoothsetup,0,0,0,0);}
631:     KSPSetUp(mglevels[i]->smoothd);
632:     if (mglevels[i]->eventsmoothsetup) {PetscLogEventEnd(mglevels[i]->eventsmoothsetup,0,0,0,0);}
633:     if (!mglevels[i]->residual) {
634:       Mat mat;
635:       KSPGetOperators(mglevels[i]->smoothd,PETSC_NULL,&mat,PETSC_NULL);
636:       PCMGSetResidual(pc,i,PCMGDefaultResidual,mat);
637:     }
638:   }
639:   for (i=1; i<n; i++) {
640:     if (mglevels[i]->smoothu && mglevels[i]->smoothu != mglevels[i]->smoothd) {
641:       Mat          downmat,downpmat;
642:       MatStructure matflag;
643:       PetscBool    opsset;

645:       /* check if operators have been set for up, if not use down operators to set them */
646:       KSPGetOperatorsSet(mglevels[i]->smoothu,&opsset,PETSC_NULL);
647:       if (!opsset) {
648:         KSPGetOperators(mglevels[i]->smoothd,&downmat,&downpmat,&matflag);
649:         KSPSetOperators(mglevels[i]->smoothu,downmat,downpmat,matflag);
650:       }

652:       KSPSetInitialGuessNonzero(mglevels[i]->smoothu,PETSC_TRUE);
653:       if (mglevels[i]->eventsmoothsetup) {PetscLogEventBegin(mglevels[i]->eventsmoothsetup,0,0,0,0);}
654:       KSPSetUp(mglevels[i]->smoothu);
655:       if (mglevels[i]->eventsmoothsetup) {PetscLogEventEnd(mglevels[i]->eventsmoothsetup,0,0,0,0);}
656:     }
657:   }

659:   /*
660:       If coarse solver is not direct method then DO NOT USE preonly 
661:   */
662:   PetscTypeCompare((PetscObject)mglevels[0]->smoothd,KSPPREONLY,&preonly);
663:   if (preonly) {
664:     PetscTypeCompare((PetscObject)cpc,PCLU,&lu);
665:     PetscTypeCompare((PetscObject)cpc,PCREDUNDANT,&redundant);
666:     PetscTypeCompare((PetscObject)cpc,PCCHOLESKY,&cholesky);
667:     PetscTypeCompare((PetscObject)cpc,PCSVD,&svd);
668:     if (!lu && !redundant && !cholesky && !svd) {
669:       KSPSetType(mglevels[0]->smoothd,KSPGMRES);
670:     }
671:   }

673:   if (!pc->setupcalled) {
674:     KSPSetFromOptions(mglevels[0]->smoothd);
675:   }

677:   if (mglevels[0]->eventsmoothsetup) {PetscLogEventBegin(mglevels[0]->eventsmoothsetup,0,0,0,0);}
678:   KSPSetUp(mglevels[0]->smoothd);
679:   if (mglevels[0]->eventsmoothsetup) {PetscLogEventEnd(mglevels[0]->eventsmoothsetup,0,0,0,0);}

681:   /*
682:      Dump the interpolation/restriction matrices plus the 
683:    Jacobian/stiffness on each level. This allows MATLAB users to 
684:    easily check if the Galerkin condition A_c = R A_f R^T is satisfied.

686:    Only support one or the other at the same time.
687:   */
688: #if defined(PETSC_USE_SOCKET_VIEWER)
689:   PetscOptionsGetBool(((PetscObject)pc)->prefix,"-pc_mg_dump_matlab",&dump,PETSC_NULL);
690:   if (dump) {
691:     viewer = PETSC_VIEWER_SOCKET_(((PetscObject)pc)->comm);
692:   }
693:   dump = PETSC_FALSE;
694: #endif
695:   PetscOptionsGetBool(((PetscObject)pc)->prefix,"-pc_mg_dump_binary",&dump,PETSC_NULL);
696:   if (dump) {
697:     viewer = PETSC_VIEWER_BINARY_(((PetscObject)pc)->comm);
698:   }

700:   if (viewer) {
701:     for (i=1; i<n; i++) {
702:       MatView(mglevels[i]->restrct,viewer);
703:     }
704:     for (i=0; i<n; i++) {
705:       KSPGetPC(mglevels[i]->smoothd,&pc);
706:       MatView(pc->mat,viewer);
707:     }
708:   }
709:   return(0);
710: }

712: /* -------------------------------------------------------------------------------------*/

716: /*@
717:    PCMGGetLevels - Gets the number of levels to use with MG.

719:    Not Collective

721:    Input Parameter:
722: .  pc - the preconditioner context

724:    Output parameter:
725: .  levels - the number of levels

727:    Level: advanced

729: .keywords: MG, get, levels, multigrid

731: .seealso: PCMGSetLevels()
732: @*/
733: PetscErrorCode  PCMGGetLevels(PC pc,PetscInt *levels)
734: {
735:   PC_MG *mg = (PC_MG*)pc->data;

740:   *levels = mg->nlevels;
741:   return(0);
742: }

746: /*@
747:    PCMGSetType - Determines the form of multigrid to use:
748:    multiplicative, additive, full, or the Kaskade algorithm.

750:    Logically Collective on PC

752:    Input Parameters:
753: +  pc - the preconditioner context
754: -  form - multigrid form, one of PC_MG_MULTIPLICATIVE, PC_MG_ADDITIVE,
755:    PC_MG_FULL, PC_MG_KASKADE

757:    Options Database Key:
758: .  -pc_mg_type <form> - Sets <form>, one of multiplicative,
759:    additive, full, kaskade   

761:    Level: advanced

763: .keywords: MG, set, method, multiplicative, additive, full, Kaskade, multigrid

765: .seealso: PCMGSetLevels()
766: @*/
767: PetscErrorCode  PCMGSetType(PC pc,PCMGType form)
768: {
769:   PC_MG                   *mg = (PC_MG*)pc->data;

774:   mg->am = form;
775:   if (form == PC_MG_MULTIPLICATIVE) pc->ops->applyrichardson = PCApplyRichardson_MG;
776:   else pc->ops->applyrichardson = 0;
777:   return(0);
778: }

782: /*@
783:    PCMGSetCycleType - Sets the type cycles to use.  Use PCMGSetCycleTypeOnLevel() for more 
784:    complicated cycling.

786:    Logically Collective on PC

788:    Input Parameters:
789: +  pc - the multigrid context 
790: -  PC_MG_CYCLE_V or PC_MG_CYCLE_W

792:    Options Database Key:
793: $  -pc_mg_cycle_type v or w

795:    Level: advanced

797: .keywords: MG, set, cycles, V-cycle, W-cycle, multigrid

799: .seealso: PCMGSetCycleTypeOnLevel()
800: @*/
801: PetscErrorCode  PCMGSetCycleType(PC pc,PCMGCycleType n)
802: {
803:   PC_MG        *mg = (PC_MG*)pc->data;
804:   PC_MG_Levels **mglevels = mg->levels;
805:   PetscInt     i,levels;

809:   if (!mglevels) SETERRQ(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
811:   levels = mglevels[0]->levels;

813:   for (i=0; i<levels; i++) {
814:     mglevels[i]->cycles  = n;
815:   }
816:   return(0);
817: }

821: /*@
822:    PCMGMultiplicativeSetCycles - Sets the number of cycles to use for each preconditioner step 
823:          of multigrid when PCMGType of PC_MG_MULTIPLICATIVE is used

825:    Logically Collective on PC

827:    Input Parameters:
828: +  pc - the multigrid context 
829: -  n - number of cycles (default is 1)

831:    Options Database Key:
832: $  -pc_mg_multiplicative_cycles n

834:    Level: advanced

836:    Notes: This is not associated with setting a v or w cycle, that is set with PCMGSetCycleType()

838: .keywords: MG, set, cycles, V-cycle, W-cycle, multigrid

840: .seealso: PCMGSetCycleTypeOnLevel(), PCMGSetCycleType()
841: @*/
842: PetscErrorCode  PCMGMultiplicativeSetCycles(PC pc,PetscInt n)
843: {
844:   PC_MG        *mg = (PC_MG*)pc->data;
845:   PC_MG_Levels **mglevels = mg->levels;
846:   PetscInt     i,levels;

850:   if (!mglevels) SETERRQ(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
852:   levels = mglevels[0]->levels;

854:   for (i=0; i<levels; i++) {
855:     mg->cyclesperpcapply  = n;
856:   }
857:   return(0);
858: }

862: /*@
863:    PCMGSetGalerkin - Causes the coarser grid matrices to be computed from the
864:       finest grid via the Galerkin process: A_i-1 = r_i * A_i * r_i^t

866:    Logically Collective on PC

868:    Input Parameters:
869: +  pc - the multigrid context
870: -  use - PETSC_TRUE to use the Galerkin process to compute coarse-level operators

872:    Options Database Key:
873: $  -pc_mg_galerkin

875:    Level: intermediate

877: .keywords: MG, set, Galerkin

879: .seealso: PCMGGetGalerkin()

881: @*/
882: PetscErrorCode PCMGSetGalerkin(PC pc,PetscBool use)
883: {
884:   PC_MG        *mg = (PC_MG*)pc->data;

888:   mg->galerkin = (PetscInt)use;
889:   return(0);
890: }

894: /*@
895:    PCMGGetGalerkin - Checks if Galerkin multigrid is being used, i.e.
896:       A_i-1 = r_i * A_i * r_i^t

898:    Not Collective

900:    Input Parameter:
901: .  pc - the multigrid context 

903:    Output Parameter:
904: .  gelerkin - PETSC_TRUE or PETSC_FALSE

906:    Options Database Key:
907: $  -pc_mg_galerkin

909:    Level: intermediate

911: .keywords: MG, set, Galerkin

913: .seealso: PCMGSetGalerkin()

915: @*/
916: PetscErrorCode  PCMGGetGalerkin(PC pc,PetscBool  *galerkin)
917: {
918:   PC_MG        *mg = (PC_MG*)pc->data;

922:   *galerkin = (PetscBool)mg->galerkin;
923:   return(0);
924: }

928: /*@
929:    PCMGSetNumberSmoothDown - Sets the number of pre-smoothing steps to
930:    use on all levels. Use PCMGGetSmootherDown() to set different 
931:    pre-smoothing steps on different levels.

933:    Logically Collective on PC

935:    Input Parameters:
936: +  mg - the multigrid context 
937: -  n - the number of smoothing steps

939:    Options Database Key:
940: .  -pc_mg_smoothdown <n> - Sets number of pre-smoothing steps

942:    Level: advanced

944: .keywords: MG, smooth, down, pre-smoothing, steps, multigrid

946: .seealso: PCMGSetNumberSmoothUp()
947: @*/
948: PetscErrorCode  PCMGSetNumberSmoothDown(PC pc,PetscInt n)
949: {
950:   PC_MG          *mg = (PC_MG*)pc->data;
951:   PC_MG_Levels   **mglevels = mg->levels;
953:   PetscInt       i,levels;

957:   if (!mglevels) SETERRQ(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
959:   levels = mglevels[0]->levels;

961:   for (i=1; i<levels; i++) {
962:     /* make sure smoother up and down are different */
963:     PCMGGetSmootherUp(pc,i,PETSC_NULL);
964:     KSPSetTolerances(mglevels[i]->smoothd,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT,n);
965:     mg->default_smoothd = n;
966:   }
967:   return(0);
968: }

972: /*@
973:    PCMGSetNumberSmoothUp - Sets the number of post-smoothing steps to use 
974:    on all levels. Use PCMGGetSmootherUp() to set different numbers of 
975:    post-smoothing steps on different levels.

977:    Logically Collective on PC

979:    Input Parameters:
980: +  mg - the multigrid context 
981: -  n - the number of smoothing steps

983:    Options Database Key:
984: .  -pc_mg_smoothup <n> - Sets number of post-smoothing steps

986:    Level: advanced

988:    Note: this does not set a value on the coarsest grid, since we assume that
989:     there is no separate smooth up on the coarsest grid.

991: .keywords: MG, smooth, up, post-smoothing, steps, multigrid

993: .seealso: PCMGSetNumberSmoothDown()
994: @*/
995: PetscErrorCode  PCMGSetNumberSmoothUp(PC pc,PetscInt n)
996: {
997:   PC_MG          *mg = (PC_MG*)pc->data;
998:   PC_MG_Levels   **mglevels = mg->levels;
1000:   PetscInt       i,levels;

1004:   if (!mglevels) SETERRQ(((PetscObject)pc)->comm,PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
1006:   levels = mglevels[0]->levels;

1008:   for (i=1; i<levels; i++) {
1009:     /* make sure smoother up and down are different */
1010:     PCMGGetSmootherUp(pc,i,PETSC_NULL);
1011:     KSPSetTolerances(mglevels[i]->smoothu,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT,n);
1012:     mg->default_smoothu = n;
1013:   }
1014:   return(0);
1015: }

1017: /* ----------------------------------------------------------------------------------------*/

1019: /*MC
1020:    PCMG - Use multigrid preconditioning. This preconditioner requires you provide additional
1021:     information about the coarser grid matrices and restriction/interpolation operators.

1023:    Options Database Keys:
1024: +  -pc_mg_levels <nlevels> - number of levels including finest
1025: .  -pc_mg_cycles v or w
1026: .  -pc_mg_smoothup <n> - number of smoothing steps after interpolation
1027: .  -pc_mg_smoothdown <n> - number of smoothing steps before applying restriction operator
1028: .  -pc_mg_type <additive,multiplicative,full,cascade> - multiplicative is the default
1029: .  -pc_mg_log - log information about time spent on each level of the solver
1030: .  -pc_mg_monitor - print information on the multigrid convergence
1031: .  -pc_mg_galerkin - use Galerkin process to compute coarser operators
1032: -  -pc_mg_dump_matlab - dumps the matrices for each level and the restriction/interpolation matrices
1033:                         to the Socket viewer for reading from MATLAB.

1035:    Notes: By default this uses GMRES on the fine grid smoother so this should be used with KSPFGMRES or the smoother changed to not use GMRES

1037:    Level: intermediate

1039:    Concepts: multigrid/multilevel

1041: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types), PC, PCMGType, PCEXOTIC
1042:            PCMGSetLevels(), PCMGGetLevels(), PCMGSetType(), PCMGSetCycleType(), PCMGSetNumberSmoothDown(),
1043:            PCMGSetNumberSmoothUp(), PCMGGetCoarseSolve(), PCMGSetResidual(), PCMGSetInterpolation(),
1044:            PCMGSetRestriction(), PCMGGetSmoother(), PCMGGetSmootherUp(), PCMGGetSmootherDown(),
1045:            PCMGSetCycleTypeOnLevel(), PCMGSetRhs(), PCMGSetX(), PCMGSetR()           
1046: M*/

1051: PetscErrorCode  PCCreate_MG(PC pc)
1052: {
1053:   PC_MG          *mg;

1057:   PetscNewLog(pc,PC_MG,&mg);
1058:   pc->data    = (void*)mg;
1059:   mg->nlevels = -1;

1061:   pc->ops->apply          = PCApply_MG;
1062:   pc->ops->setup          = PCSetUp_MG;
1063:   pc->ops->reset          = PCReset_MG;
1064:   pc->ops->destroy        = PCDestroy_MG;
1065:   pc->ops->setfromoptions = PCSetFromOptions_MG;
1066:   pc->ops->view           = PCView_MG;
1067:   return(0);
1068: }