Actual source code: mg.c

  1: #define PETSCKSP_DLL

  3: /*
  4:     Defines the multigrid preconditioner interface.
  5: */
 6:  #include src/ksp/pc/impls/mg/mgimpl.h


 11: PetscErrorCode PCMGMCycle_Private(PC pc,PC_MG **mglevels,PetscTruth *converged)
 12: {
 13:   PC_MG          *mg = *mglevels,*mgc;
 15:   PetscInt       cycles = (PetscInt) mg->cycles;

 18:   if (converged) *converged = PETSC_FALSE;

 21:   KSPSolve(mg->smoothd,mg->b,mg->x);  /* pre-smooth */
 23:   if (mg->level) {  /* not the coarsest grid */
 25:     (*mg->residual)(mg->A,mg->b,mg->x,mg->r);

 28:     /* if on finest level and have convergence criteria set */
 29:     if (mg->level == mg->levels-1 && mg->ttol) {
 30:       PetscReal rnorm;
 31:       VecNorm(mg->r,NORM_2,&rnorm);
 32:       if (rnorm <= mg->ttol) {
 33:         *converged = PETSC_TRUE;
 34:         if (rnorm < mg->abstol) {
 35:           PetscInfo2(pc,"Linear solver has converged. Residual norm %G is less than absolute tolerance %G\n",rnorm,mg->abstol);
 36:         } else {
 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 = *(mglevels - 1);
 45:     MatRestrict(mg->restrct,mg->r,mgc->b);
 47:     VecSet(mgc->x,0.0);
 48:     while (cycles--) {
 49:       PCMGMCycle_Private(pc,mglevels-1,converged);
 50:     }
 52:     MatInterpolateAdd(mg->interpolate,mgc->x,mg->x,mg->x);
 55:     KSPSolve(mg->smoothu,mg->b,mg->x);    /* post smooth */
 57:   }
 58:   return(0);
 59: }

 61: /*
 62:        PCMGCreate_Private - Creates a PC_MG structure for use with the
 63:                multigrid code. Level 0 is the coarsest. (But the 
 64:                finest level is stored first in the array).

 66: */
 69: static PetscErrorCode PCMGCreate_Private(MPI_Comm comm,PetscInt levels,PC pc,MPI_Comm *comms,PC_MG ***result)
 70: {
 71:   PC_MG          **mg;
 73:   PetscInt       i;
 74:   PetscMPIInt    size;
 75:   const char     *prefix;
 76:   PC             ipc;

 79:   PetscMalloc(levels*sizeof(PC_MG*),&mg);
 80:   PetscLogObjectMemory(pc,levels*(sizeof(PC_MG*)));

 82:   PCGetOptionsPrefix(pc,&prefix);

 84:   for (i=0; i<levels; i++) {
 85:     PetscNewLog(pc,PC_MG,&mg[i]);
 86:     mg[i]->level           = i;
 87:     mg[i]->levels          = levels;
 88:     mg[i]->cycles          = PC_MG_CYCLE_V;
 89:     mg[i]->galerkin        = PETSC_FALSE;
 90:     mg[i]->galerkinused    = PETSC_FALSE;
 91:     mg[i]->default_smoothu = 1;
 92:     mg[i]->default_smoothd = 1;

 94:     if (comms) comm = comms[i];
 95:     KSPCreate(comm,&mg[i]->smoothd);
 96:     KSPSetTolerances(mg[i]->smoothd,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT, mg[i]->default_smoothd);
 97:     KSPSetOptionsPrefix(mg[i]->smoothd,prefix);

 99:     /* do special stuff for coarse grid */
100:     if (!i && levels > 1) {
101:       KSPAppendOptionsPrefix(mg[0]->smoothd,"mg_coarse_");

103:       /* coarse solve is (redundant) LU by default */
104:       KSPSetType(mg[0]->smoothd,KSPPREONLY);
105:       KSPGetPC(mg[0]->smoothd,&ipc);
106:       MPI_Comm_size(comm,&size);
107:       if (size > 1) {
108:         PCSetType(ipc,PCREDUNDANT);
109:       } else {
110:         PCSetType(ipc,PCLU);
111:       }

113:     } else {
114:       char tprefix[128];
115:       sprintf(tprefix,"mg_levels_%d_",(int)i);
116:       KSPAppendOptionsPrefix(mg[i]->smoothd,tprefix);
117:     }
118:     PetscLogObjectParent(pc,mg[i]->smoothd);
119:     mg[i]->smoothu             = mg[i]->smoothd;
120:     mg[i]->rtol                = 0.0;
121:     mg[i]->abstol              = 0.0;
122:     mg[i]->dtol                = 0.0;
123:     mg[i]->ttol                = 0.0;
124:     mg[i]->eventsmoothsetup    = 0;
125:     mg[i]->eventsmoothsolve    = 0;
126:     mg[i]->eventresidual       = 0;
127:     mg[i]->eventinterprestrict = 0;
128:     mg[i]->cyclesperpcapply    = 1;
129:   }
130:   *result = mg;
131:   return(0);
132: }

136: static PetscErrorCode PCDestroy_MG(PC pc)
137: {
138:   PC_MG          **mg = (PC_MG**)pc->data;
140:   PetscInt       i,n;

143:   if (!mg) return(0);
144:   n = mg[0]->levels;
145:   for (i=0; i<n-1; i++) {
146:     if (mg[i+1]->r) {VecDestroy(mg[i+1]->r);}
147:     if (mg[i]->b) {VecDestroy(mg[i]->b);}
148:     if (mg[i]->x) {VecDestroy(mg[i]->x);}
149:     if (mg[i+1]->restrct) {MatDestroy(mg[i+1]->restrct);}
150:     if (mg[i+1]->interpolate) {MatDestroy(mg[i+1]->interpolate);}
151:   }

153:   for (i=0; i<n; i++) {
154:     if (mg[i]->smoothd != mg[i]->smoothu) {
155:       KSPDestroy(mg[i]->smoothd);
156:     }
157:     KSPDestroy(mg[i]->smoothu);
158:     PetscFree(mg[i]);
159:   }
160:   PetscFree(mg);
161:   return(0);
162: }



166: EXTERN PetscErrorCode PCMGACycle_Private(PC_MG**);
167: EXTERN PetscErrorCode PCMGFCycle_Private(PC,PC_MG**);
168: EXTERN PetscErrorCode PCMGKCycle_Private(PC_MG**);

170: /*
171:    PCApply_MG - Runs either an additive, multiplicative, Kaskadic
172:              or full cycle of multigrid. 

174:   Note: 
175:   A simple wrapper which calls PCMGMCycle(),PCMGACycle(), or PCMGFCycle(). 
176: */
179: static PetscErrorCode PCApply_MG(PC pc,Vec b,Vec x)
180: {
181:   PC_MG          **mg = (PC_MG**)pc->data;
183:   PetscInt       levels = mg[0]->levels,i;

186:   mg[levels-1]->b = b;
187:   mg[levels-1]->x = x;
188:   if (!mg[levels-1]->r && mg[0]->am != PC_MG_ADDITIVE && levels > 1) {
189:     Vec tvec;
190:     VecDuplicate(mg[levels-1]->b,&tvec);
191:     PCMGSetR(pc,levels-1,tvec);
192:     VecDestroy(tvec);
193:   }
194:   if (mg[0]->am == PC_MG_MULTIPLICATIVE) {
195:     VecSet(x,0.0);
196:     for (i=0; i<mg[0]->cyclesperpcapply; i++) {
197:       PCMGMCycle_Private(pc,mg+levels-1,PETSC_NULL);
198:     }
199:   }
200:   else if (mg[0]->am == PC_MG_ADDITIVE) {
201:     PCMGACycle_Private(mg);
202:   }
203:   else if (mg[0]->am == PC_MG_KASKADE) {
204:     PCMGKCycle_Private(mg);
205:   }
206:   else {
207:     PCMGFCycle_Private(pc,mg);
208:   }
209:   return(0);
210: }

214: static PetscErrorCode PCApplyRichardson_MG(PC pc,Vec b,Vec x,Vec w,PetscReal rtol,PetscReal abstol, PetscReal dtol,PetscInt its)
215: {
216:   PC_MG          **mg = (PC_MG**)pc->data;
218:   PetscInt       levels = mg[0]->levels;
219:   PetscTruth     converged = PETSC_FALSE;

222:   mg[levels-1]->b    = b;
223:   mg[levels-1]->x    = x;

225:   mg[levels-1]->rtol = rtol;
226:   mg[levels-1]->abstol = abstol;
227:   mg[levels-1]->dtol = dtol;
228:   if (rtol) {
229:     /* compute initial residual norm for relative convergence test */
230:     PetscReal rnorm;
231:     (*mg[levels-1]->residual)(mg[levels-1]->A,b,x,w);
232:     VecNorm(w,NORM_2,&rnorm);
233:     mg[levels-1]->ttol = PetscMax(rtol*rnorm,abstol);
234:   } else if (abstol) {
235:     mg[levels-1]->ttol = abstol;
236:   } else {
237:     mg[levels-1]->ttol = 0.0;
238:   }

240:   while (its-- && !converged) {
241:     PCMGMCycle_Private(pc,mg+levels-1,&converged);
242:   }
243:   return(0);
244: }

248: PetscErrorCode PCSetFromOptions_MG(PC pc)
249: {
251:   PetscInt       m,levels = 1,cycles;
252:   PetscTruth     flg;
253:   PC_MG          **mg = (PC_MG**)pc->data;
254:   PCMGType       mgtype = PC_MG_ADDITIVE;
255:   PCMGCycleType  mgctype;

258:   PetscOptionsHead("Multigrid options");
259:     if (!pc->data) {
260:       PetscOptionsInt("-pc_mg_levels","Number of Levels","PCMGSetLevels",levels,&levels,&flg);
261:       PCMGSetLevels(pc,levels,PETSC_NULL);
262:       mg = (PC_MG**)pc->data;
263:     }
264:     mgctype = (PCMGCycleType) mg[0]->cycles;
265:     PetscOptionsEnum("-pc_mg_cycle_type","V cycle or for W-cycle","PCMGSetCycleType",PCMGCycleTypes,(PetscEnum)mgctype,(PetscEnum*)&mgctype,&flg);
266:     if (flg) {
267:       PCMGSetCycleType(pc,mgctype);
268:     };
269:     PetscOptionsName("-pc_mg_galerkin","Use Galerkin process to compute coarser operators","PCMGSetGalerkin",&flg);
270:     if (flg) {
271:       PCMGSetGalerkin(pc);
272:     }
273:     PetscOptionsInt("-pc_mg_smoothup","Number of post-smoothing steps","PCMGSetNumberSmoothUp",1,&m,&flg);
274:     if (flg) {
275:       PCMGSetNumberSmoothUp(pc,m);
276:     }
277:     PetscOptionsInt("-pc_mg_smoothdown","Number of pre-smoothing steps","PCMGSetNumberSmoothDown",1,&m,&flg);
278:     if (flg) {
279:       PCMGSetNumberSmoothDown(pc,m);
280:     }
281:     PetscOptionsEnum("-pc_mg_type","Multigrid type","PCMGSetType",PCMGTypes,(PetscEnum)mgtype,(PetscEnum*)&mgtype,&flg);
282:     if (flg) {
283:       PCMGSetType(pc,mgtype);
284:     }
285:     if (mg[0]->am == PC_MG_MULTIPLICATIVE) {
286:       PetscOptionsInt("-pc_mg_multiplicative_cycles","Number of cycles for each preconditioner step","PCMGSetLevels",mg[0]->cyclesperpcapply,&cycles,&flg);
287:       if (flg) {
288:         PCMGMultiplicativeSetCycles(pc,cycles);
289:       }
290:     }
291:     PetscOptionsName("-pc_mg_log","Log times for each multigrid level","None",&flg);
292:     if (flg) {
293:       PetscInt i;
294:       char     eventname[128];
295:       if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
296:       levels = mg[0]->levels;
297:       for (i=0; i<levels; i++) {
298:         sprintf(eventname,"MGSetup Level %d",(int)i);
300:         sprintf(eventname,"MGSmooth Level %d",(int)i);
302:         if (i) {
303:           sprintf(eventname,"MGResid Level %d",(int)i);
305:           sprintf(eventname,"MGInterp Level %d",(int)i);
307:         }
308:       }
309:     }
310:   PetscOptionsTail();
311:   return(0);
312: }

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

319: static PetscErrorCode PCView_MG(PC pc,PetscViewer viewer)
320: {
321:   PC_MG          **mg = (PC_MG**)pc->data;
323:   PetscInt       levels = mg[0]->levels,i;
324:   PetscTruth     iascii;

327:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
328:   if (iascii) {
329:     PetscViewerASCIIPrintf(viewer,"  MG: type is %s, levels=%D cycles=%s, pre-smooths=%D, post-smooths=%D\n",
330:                                   PCMGTypes[mg[0]->am],levels,(mg[0]->cycles == PC_MG_CYCLE_V) ? "v" : "w",
331:                                   mg[0]->default_smoothd,mg[0]->default_smoothu);
332:     if (mg[0]->galerkin) {
333:       PetscViewerASCIIPrintf(viewer,"    Using Galerkin computed coarse grid matrices\n");
334:     }
335:     for (i=0; i<levels; i++) {
336:       if (!i) {
337:         PetscViewerASCIIPrintf(viewer,"Coarse gride solver -- level %D -------------------------------\n",i);
338:       } else {
339:         PetscViewerASCIIPrintf(viewer,"Down solver (pre-smoother) on level %D -------------------------------\n",i);
340:       }
341:       PetscViewerASCIIPushTab(viewer);
342:       KSPView(mg[i]->smoothd,viewer);
343:       PetscViewerASCIIPopTab(viewer);
344:       if (i && mg[i]->smoothd == mg[i]->smoothu) {
345:         PetscViewerASCIIPrintf(viewer,"Up solver (post-smoother) same as down solver (pre-smoother)\n");
346:       } else if (i){
347:         PetscViewerASCIIPrintf(viewer,"Up solver (post-smoother) on level %D -------------------------------\n",i);
348:         PetscViewerASCIIPushTab(viewer);
349:         KSPView(mg[i]->smoothu,viewer);
350:         PetscViewerASCIIPopTab(viewer);
351:       }
352:     }
353:   } else {
354:     SETERRQ1(PETSC_ERR_SUP,"Viewer type %s not supported for PCMG",((PetscObject)viewer)->type_name);
355:   }
356:   return(0);
357: }

359: /*
360:     Calls setup for the KSP on each level
361: */
364: static PetscErrorCode PCSetUp_MG(PC pc)
365: {
366:   PC_MG                   **mg = (PC_MG**)pc->data;
367:   PetscErrorCode          ierr;
368:   PetscInt                i,n = mg[0]->levels;
369:   PC                      cpc,mpc;
370:   PetscTruth              preonly,lu,redundant,cholesky,monitor = PETSC_FALSE,dump,opsset;
371:   PetscViewerASCIIMonitor ascii;
372:   PetscViewer             viewer = PETSC_NULL;
373:   MPI_Comm                comm;
374:   Mat                     dA,dB;
375:   MatStructure            uflag;
376:   Vec                     tvec;


380:   /* If user did not provide fine grid operators OR operator was not updated since last global KSPSetOperators() */
381:   /* so use those from global PC */
382:   /* Is this what we always want? What if user wants to keep old one? */
383:   KSPGetOperatorsSet(mg[n-1]->smoothd,PETSC_NULL,&opsset);
384:   KSPGetPC(mg[0]->smoothd,&cpc);
385:   KSPGetPC(mg[n-1]->smoothd,&mpc);
386:   if (!opsset || ((cpc->setupcalled == 1) && (mpc->setupcalled == 2))) {
387:     PetscInfo(pc,"Using outer operators to define finest grid operator \n  because PCMGGetSmoother(pc,nlevels-1,&ksp);KSPSetOperators(ksp,...); was not called.\n");
388:     KSPSetOperators(mg[n-1]->smoothd,pc->mat,pc->pmat,pc->flag);
389:   }

391:   if (mg[0]->galerkin) {
392:     Mat B;
393:     mg[0]->galerkinused = PETSC_TRUE;
394:     /* currently only handle case where mat and pmat are the same on coarser levels */
395:     KSPGetOperators(mg[n-1]->smoothd,&dA,&dB,&uflag);
396:     if (!pc->setupcalled) {
397:       for (i=n-2; i>-1; i--) {
398:         MatPtAP(dB,mg[i+1]->interpolate,MAT_INITIAL_MATRIX,1.0,&B);
399:         KSPSetOperators(mg[i]->smoothd,B,B,uflag);
400:         if (i != n-2) {PetscObjectDereference((PetscObject)dB);}
401:         dB   = B;
402:       }
403:       PetscObjectDereference((PetscObject)dB);
404:     } else {
405:       for (i=n-2; i>-1; i--) {
406:         KSPGetOperators(mg[i]->smoothd,PETSC_NULL,&B,PETSC_NULL);
407:         MatPtAP(dB,mg[i+1]->interpolate,MAT_REUSE_MATRIX,1.0,&B);
408:         KSPSetOperators(mg[i]->smoothd,B,B,uflag);
409:         dB   = B;
410:       }
411:     }
412:   }

414:   if (!pc->setupcalled) {
415:     PetscOptionsHasName(0,"-pc_mg_monitor",&monitor);
416: 
417:     for (i=0; i<n; i++) {
418:       if (monitor) {
419:         PetscObjectGetComm((PetscObject)mg[i]->smoothd,&comm);
420:         PetscViewerASCIIMonitorCreate(comm,"stdout",n-i,&ascii);
421:         KSPMonitorSet(mg[i]->smoothd,KSPMonitorDefault,ascii,(PetscErrorCode(*)(void*))PetscViewerASCIIMonitorDestroy);
422:       }
423:       KSPSetFromOptions(mg[i]->smoothd);
424:     }
425:     for (i=1; i<n; i++) {
426:       if (mg[i]->smoothu && (mg[i]->smoothu != mg[i]->smoothd)) {
427:         if (monitor) {
428:           PetscObjectGetComm((PetscObject)mg[i]->smoothu,&comm);
429:           PetscViewerASCIIMonitorCreate(comm,"stdout",n-i,&ascii);
430:           KSPMonitorSet(mg[i]->smoothu,KSPMonitorDefault,ascii,(PetscErrorCode(*)(void*))PetscViewerASCIIMonitorDestroy);
431:         }
432:         KSPSetFromOptions(mg[i]->smoothu);
433:       }
434:     }
435:     for (i=1; i<n; i++) {
436:       if (!mg[i]->residual) {
437:         Mat mat;
438:         KSPGetOperators(mg[i]->smoothd,PETSC_NULL,&mat,PETSC_NULL);
439:         PCMGSetResidual(pc,i,PCMGDefaultResidual,mat);
440:       }
441:       if (mg[i]->restrct && !mg[i]->interpolate) {
442:         PCMGSetInterpolation(pc,i,mg[i]->restrct);
443:       }
444:       if (!mg[i]->restrct && mg[i]->interpolate) {
445:         PCMGSetRestriction(pc,i,mg[i]->interpolate);
446:       }
447: #if defined(PETSC_USE_DEBUG)
448:       if (!mg[i]->restrct || !mg[i]->interpolate) {
449:         SETERRQ1(PETSC_ERR_ARG_WRONGSTATE,"Need to set restriction or interpolation on level %d",(int)i);
450:       }
451: #endif
452:     }
453:     for (i=0; i<n-1; i++) {
454:       if (!mg[i]->b) {
455:         Vec *vec;
456:         KSPGetVecs(mg[i]->smoothd,1,&vec,0,PETSC_NULL);
457:         PCMGSetRhs(pc,i,*vec);
458:         PetscFree(vec);
459:       }
460:       if (!mg[i]->r && i) {
461:         VecDuplicate(mg[i]->b,&tvec);
462:         PCMGSetR(pc,i,tvec);
463:         VecDestroy(tvec);
464:       }
465:       if (!mg[i]->x) {
466:         VecDuplicate(mg[i]->b,&tvec);
467:         PCMGSetX(pc,i,tvec);
468:         VecDestroy(tvec);
469:       }
470:     }
471:   }


474:   for (i=1; i<n; i++) {
475:     if (mg[i]->smoothu == mg[i]->smoothd) {
476:       /* if doing only down then initial guess is zero */
477:       KSPSetInitialGuessNonzero(mg[i]->smoothd,PETSC_TRUE);
478:     }
480:     KSPSetUp(mg[i]->smoothd);
482:   }
483:   for (i=1; i<n; i++) {
484:     if (mg[i]->smoothu && mg[i]->smoothu != mg[i]->smoothd) {
485:       Mat          downmat,downpmat;
486:       MatStructure matflag;
487:       PetscTruth   opsset;

489:       /* check if operators have been set for up, if not use down operators to set them */
490:       KSPGetOperatorsSet(mg[i]->smoothu,&opsset,PETSC_NULL);
491:       if (!opsset) {
492:         KSPGetOperators(mg[i]->smoothd,&downmat,&downpmat,&matflag);
493:         KSPSetOperators(mg[i]->smoothu,downmat,downpmat,matflag);
494:       }

496:       KSPSetInitialGuessNonzero(mg[i]->smoothu,PETSC_TRUE);
498:       KSPSetUp(mg[i]->smoothu);
500:     }
501:   }

503:   /*
504:       If coarse solver is not direct method then DO NOT USE preonly 
505:   */
506:   PetscTypeCompare((PetscObject)mg[0]->smoothd,KSPPREONLY,&preonly);
507:   if (preonly) {
508:     PetscTypeCompare((PetscObject)cpc,PCLU,&lu);
509:     PetscTypeCompare((PetscObject)cpc,PCREDUNDANT,&redundant);
510:     PetscTypeCompare((PetscObject)cpc,PCCHOLESKY,&cholesky);
511:     if (!lu && !redundant && !cholesky) {
512:       KSPSetType(mg[0]->smoothd,KSPGMRES);
513:     }
514:   }

516:   if (!pc->setupcalled) {
517:     if (monitor) {
518:       PetscObjectGetComm((PetscObject)mg[0]->smoothd,&comm);
519:       PetscViewerASCIIMonitorCreate(comm,"stdout",n,&ascii);
520:       KSPMonitorSet(mg[0]->smoothd,KSPMonitorDefault,ascii,(PetscErrorCode(*)(void*))PetscViewerASCIIMonitorDestroy);
521:     }
522:     KSPSetFromOptions(mg[0]->smoothd);
523:   }

526:   KSPSetUp(mg[0]->smoothd);

529:   /*
530:      Dump the interpolation/restriction matrices plus the 
531:    Jacobian/stiffness on each level. This allows Matlab users to 
532:    easily check if the Galerkin condition A_c = R A_f R^T is satisfied.

534:    Only support one or the other at the same time.
535:   */
536: #if defined(PETSC_USE_SOCKET_VIEWER)
537:   PetscOptionsHasName(((PetscObject)pc)->prefix,"-pc_mg_dump_matlab",&dump);
538:   if (dump) {
539:     viewer = PETSC_VIEWER_SOCKET_(((PetscObject)pc)->comm);
540:   }
541: #endif
542:   PetscOptionsHasName(((PetscObject)pc)->prefix,"-pc_mg_dump_binary",&dump);
543:   if (dump) {
544:     viewer = PETSC_VIEWER_BINARY_(((PetscObject)pc)->comm);
545:   }

547:   if (viewer) {
548:     for (i=1; i<n; i++) {
549:       MatView(mg[i]->restrct,viewer);
550:     }
551:     for (i=0; i<n; i++) {
552:       KSPGetPC(mg[i]->smoothd,&pc);
553:       MatView(pc->mat,viewer);
554:     }
555:   }
556:   return(0);
557: }

559: /* -------------------------------------------------------------------------------------*/

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

567:    Collective on PC

569:    Input Parameters:
570: +  pc - the preconditioner context
571: .  levels - the number of levels
572: -  comms - optional communicators for each level; this is to allow solving the coarser problems
573:            on smaller sets of processors. Use PETSC_NULL_OBJECT for default in Fortran

575:    Level: intermediate

577:    Notes:
578:      If the number of levels is one then the multigrid uses the -mg_levels prefix
579:   for setting the level options rather than the -mg_coarse prefix.

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

583: .seealso: PCMGSetType(), PCMGGetLevels()
584: @*/
585: PetscErrorCode  PCMGSetLevels(PC pc,PetscInt levels,MPI_Comm *comms)
586: {
588:   PC_MG          **mg=0;


593:   if (pc->data) {
594:     SETERRQ(PETSC_ERR_ORDER,"Number levels already set for MG\n\
595:     make sure that you call PCMGSetLevels() before KSPSetFromOptions()");
596:   }
597:   PCMGCreate_Private(((PetscObject)pc)->comm,levels,pc,comms,&mg);
598:   mg[0]->am                = PC_MG_MULTIPLICATIVE;
599:   pc->data                 = (void*)mg;
600:   pc->ops->applyrichardson = PCApplyRichardson_MG;
601:   return(0);
602: }

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

609:    Not Collective

611:    Input Parameter:
612: .  pc - the preconditioner context

614:    Output parameter:
615: .  levels - the number of levels

617:    Level: advanced

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

621: .seealso: PCMGSetLevels()
622: @*/
623: PetscErrorCode  PCMGGetLevels(PC pc,PetscInt *levels)
624: {
625:   PC_MG  **mg;


631:   mg      = (PC_MG**)pc->data;
632:   *levels = mg[0]->levels;
633:   return(0);
634: }

638: /*@
639:    PCMGSetType - Determines the form of multigrid to use:
640:    multiplicative, additive, full, or the Kaskade algorithm.

642:    Collective on PC

644:    Input Parameters:
645: +  pc - the preconditioner context
646: -  form - multigrid form, one of PC_MG_MULTIPLICATIVE, PC_MG_ADDITIVE,
647:    PC_MG_FULL, PC_MG_KASKADE

649:    Options Database Key:
650: .  -pc_mg_type <form> - Sets <form>, one of multiplicative,
651:    additive, full, kaskade   

653:    Level: advanced

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

657: .seealso: PCMGSetLevels()
658: @*/
659: PetscErrorCode  PCMGSetType(PC pc,PCMGType form)
660: {
661:   PC_MG **mg;

665:   mg = (PC_MG**)pc->data;

667:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
668:   mg[0]->am = form;
669:   if (form == PC_MG_MULTIPLICATIVE) pc->ops->applyrichardson = PCApplyRichardson_MG;
670:   else pc->ops->applyrichardson = 0;
671:   return(0);
672: }

676: /*@
677:    PCMGSetCycleType - Sets the type cycles to use.  Use PCMGSetCycleTypeOnLevel() for more 
678:    complicated cycling.

680:    Collective on PC

682:    Input Parameters:
683: +  pc - the multigrid context 
684: -  PC_MG_CYCLE_V or PC_MG_CYCLE_W

686:    Options Database Key:
687: $  -pc_mg_cycle_type v or w

689:    Level: advanced

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

693: .seealso: PCMGSetCycleTypeOnLevel()
694: @*/
695: PetscErrorCode  PCMGSetCycleType(PC pc,PCMGCycleType n)
696: {
697:   PC_MG    **mg;
698:   PetscInt i,levels;

702:   mg     = (PC_MG**)pc->data;
703:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
704:   levels = mg[0]->levels;

706:   for (i=0; i<levels; i++) {
707:     mg[i]->cycles  = n;
708:   }
709:   return(0);
710: }

714: /*@
715:    PCMGMultiplicativeSetCycles - Sets the number of cycles to use for each preconditioner step 
716:          of multigrid when PCMGType of PC_MG_MULTIPLICATIVE is used

718:    Collective on PC

720:    Input Parameters:
721: +  pc - the multigrid context 
722: -  n - number of cycles (default is 1)

724:    Options Database Key:
725: $  -pc_mg_multiplicative_cycles n

727:    Level: advanced

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

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

733: .seealso: PCMGSetCycleTypeOnLevel(), PCMGSetCycleType()
734: @*/
735: PetscErrorCode  PCMGMultiplicativeSetCycles(PC pc,PetscInt n)
736: {
737:   PC_MG    **mg;
738:   PetscInt i,levels;

742:   mg     = (PC_MG**)pc->data;
743:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
744:   levels = mg[0]->levels;

746:   for (i=0; i<levels; i++) {
747:     mg[i]->cyclesperpcapply  = n;
748:   }
749:   return(0);
750: }

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

758:    Collective on PC

760:    Input Parameters:
761: .  pc - the multigrid context 

763:    Options Database Key:
764: $  -pc_mg_galerkin

766:    Level: intermediate

768: .keywords: MG, set, Galerkin

770: .seealso: PCMGGetGalerkin()

772: @*/
773: PetscErrorCode  PCMGSetGalerkin(PC pc)
774: {
775:   PC_MG    **mg;
776:   PetscInt i,levels;

780:   mg     = (PC_MG**)pc->data;
781:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
782:   levels = mg[0]->levels;

784:   for (i=0; i<levels; i++) {
785:     mg[i]->galerkin = PETSC_TRUE;
786:   }
787:   return(0);
788: }

792: /*@
793:    PCMGGetGalerkin - Checks if Galerkin multigrid is being used, i.e.
794:       A_i-1 = r_i * A_i * r_i^t

796:    Not Collective

798:    Input Parameter:
799: .  pc - the multigrid context 

801:    Output Parameter:
802: .  gelerkin - PETSC_TRUE or PETSC_FALSE

804:    Options Database Key:
805: $  -pc_mg_galerkin

807:    Level: intermediate

809: .keywords: MG, set, Galerkin

811: .seealso: PCMGSetGalerkin()

813: @*/
814: PetscErrorCode  PCMGGetGalerkin(PC pc,PetscTruth *galerkin)
815: {
816:   PC_MG    **mg;

820:   mg     = (PC_MG**)pc->data;
821:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
822:   *galerkin = mg[0]->galerkin;
823:   return(0);
824: }

828: /*@
829:    PCMGSetNumberSmoothDown - Sets the number of pre-smoothing steps to
830:    use on all levels. Use PCMGGetSmootherDown() to set different 
831:    pre-smoothing steps on different levels.

833:    Collective on PC

835:    Input Parameters:
836: +  mg - the multigrid context 
837: -  n - the number of smoothing steps

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

842:    Level: advanced

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

846: .seealso: PCMGSetNumberSmoothUp()
847: @*/
848: PetscErrorCode  PCMGSetNumberSmoothDown(PC pc,PetscInt n)
849: {
850:   PC_MG          **mg;
852:   PetscInt       i,levels;

856:   mg     = (PC_MG**)pc->data;
857:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
858:   levels = mg[0]->levels;

860:   for (i=1; i<levels; i++) {
861:     /* make sure smoother up and down are different */
862:     PCMGGetSmootherUp(pc,i,PETSC_NULL);
863:     KSPSetTolerances(mg[i]->smoothd,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT,n);
864:     mg[i]->default_smoothd = n;
865:   }
866:   return(0);
867: }

871: /*@
872:    PCMGSetNumberSmoothUp - Sets the number of post-smoothing steps to use 
873:    on all levels. Use PCMGGetSmootherUp() to set different numbers of 
874:    post-smoothing steps on different levels.

876:    Collective on PC

878:    Input Parameters:
879: +  mg - the multigrid context 
880: -  n - the number of smoothing steps

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

885:    Level: advanced

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

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

892: .seealso: PCMGSetNumberSmoothDown()
893: @*/
894: PetscErrorCode  PCMGSetNumberSmoothUp(PC pc,PetscInt n)
895: {
896:   PC_MG          **mg;
898:   PetscInt       i,levels;

902:   mg     = (PC_MG**)pc->data;
903:   if (!mg) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must set MG levels before calling");
904:   levels = mg[0]->levels;

906:   for (i=1; i<levels; i++) {
907:     /* make sure smoother up and down are different */
908:     PCMGGetSmootherUp(pc,i,PETSC_NULL);
909:     KSPSetTolerances(mg[i]->smoothu,PETSC_DEFAULT,PETSC_DEFAULT,PETSC_DEFAULT,n);
910:     mg[i]->default_smoothu = n;
911:   }
912:   return(0);
913: }

915: /* ----------------------------------------------------------------------------------------*/

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

921:    Options Database Keys:
922: +  -pc_mg_levels <nlevels> - number of levels including finest
923: .  -pc_mg_cycles v or w
924: .  -pc_mg_smoothup <n> - number of smoothing steps after interpolation
925: .  -pc_mg_smoothdown <n> - number of smoothing steps before applying restriction operator
926: .  -pc_mg_type <additive,multiplicative,full,cascade> - multiplicative is the default
927: .  -pc_mg_log - log information about time spent on each level of the solver
928: .  -pc_mg_monitor - print information on the multigrid convergence
929: .  -pc_mg_galerkin - use Galerkin process to compute coarser operators
930: -  -pc_mg_dump_matlab - dumps the matrices for each level and the restriction/interpolation matrices
931:                         to the Socket viewer for reading from Matlab.

933:    Notes:

935:    Level: intermediate

937:    Concepts: multigrid/multilevel

939: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types), PC, PCMGType, 
940:            PCMGSetLevels(), PCMGGetLevels(), PCMGSetType(), PCMGSetCycleType(), PCMGSetNumberSmoothDown(),
941:            PCMGSetNumberSmoothUp(), PCMGGetCoarseSolve(), PCMGSetResidual(), PCMGSetInterpolation(),
942:            PCMGSetRestriction(), PCMGGetSmoother(), PCMGGetSmootherUp(), PCMGGetSmootherDown(),
943:            PCMGSetCycleTypeOnLevel(), PCMGSetRhs(), PCMGSetX(), PCMGSetR()           
944: M*/

949: PetscErrorCode  PCCreate_MG(PC pc)
950: {
952:   pc->ops->apply          = PCApply_MG;
953:   pc->ops->setup          = PCSetUp_MG;
954:   pc->ops->destroy        = PCDestroy_MG;
955:   pc->ops->setfromoptions = PCSetFromOptions_MG;
956:   pc->ops->view           = PCView_MG;

958:   pc->data                = (void*)0;
959:   return(0);
960: }