Actual source code: itcl.c

  1: #define PETSCKSP_DLL

  3: /*
  4:     Code for setting KSP options from the options database.
  5: */

 7:  #include include/private/kspimpl.h
 8:  #include petscsys.h

 10: /*
 11:        We retain a list of functions that also take KSP command 
 12:     line options. These are called at the end KSPSetFromOptions()
 13: */
 14: #define MAXSETFROMOPTIONS 5
 15: PetscInt numberofsetfromoptions = 0;
 16: PetscErrorCode (*othersetfromoptions[MAXSETFROMOPTIONS])(KSP) = {0};


 22: /*@C
 23:     KSPAddOptionsChecker - Adds an additional function to check for KSP options.

 25:     Not Collective

 27:     Input Parameter:
 28: .   kspcheck - function that checks for options

 30:     Level: developer

 32: .keywords: KSP, add, options, checker

 34: .seealso: KSPSetFromOptions()
 35: @*/
 36: PetscErrorCode  KSPAddOptionsChecker(PetscErrorCode (*kspcheck)(KSP))
 37: {
 39:   if (numberofsetfromoptions >= MAXSETFROMOPTIONS) {
 40:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many options checkers, only 5 allowed");
 41:   }

 43:   othersetfromoptions[numberofsetfromoptions++] = kspcheck;
 44:   return(0);
 45: }

 49: /*@C
 50:    KSPSetOptionsPrefix - Sets the prefix used for searching for all 
 51:    KSP options in the database.

 53:    Collective on KSP

 55:    Input Parameters:
 56: +  ksp - the Krylov context
 57: -  prefix - the prefix string to prepend to all KSP option requests

 59:    Notes:
 60:    A hyphen (-) must NOT be given at the beginning of the prefix name.
 61:    The first character of all runtime options is AUTOMATICALLY the
 62:    hyphen.

 64:    For example, to distinguish between the runtime options for two
 65:    different KSP contexts, one could call
 66: .vb
 67:       KSPSetOptionsPrefix(ksp1,"sys1_")
 68:       KSPSetOptionsPrefix(ksp2,"sys2_")
 69: .ve

 71:    This would enable use of different options for each system, such as
 72: .vb
 73:       -sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3
 74:       -sys2_ksp_type bcgs  -sys2_ksp_rtol 1.e-4
 75: .ve

 77:    Level: advanced

 79: .keywords: KSP, set, options, prefix, database

 81: .seealso: KSPAppendOptionsPrefix(), KSPGetOptionsPrefix()
 82: @*/
 83: PetscErrorCode  KSPSetOptionsPrefix(KSP ksp,const char prefix[])
 84: {
 88:   PCSetOptionsPrefix(ksp->pc,prefix);
 89:   PetscObjectSetOptionsPrefix((PetscObject)ksp,prefix);
 90:   return(0);
 91: }
 92: 
 95: /*@C
 96:    KSPAppendOptionsPrefix - Appends to the prefix used for searching for all 
 97:    KSP options in the database.

 99:    Collective on KSP

101:    Input Parameters:
102: +  ksp - the Krylov context
103: -  prefix - the prefix string to prepend to all KSP option requests

105:    Notes:
106:    A hyphen (-) must NOT be given at the beginning of the prefix name.
107:    The first character of all runtime options is AUTOMATICALLY the hyphen.

109:    Level: advanced

111: .keywords: KSP, append, options, prefix, database

113: .seealso: KSPSetOptionsPrefix(), KSPGetOptionsPrefix()
114: @*/
115: PetscErrorCode  KSPAppendOptionsPrefix(KSP ksp,const char prefix[])
116: {
120:   PCAppendOptionsPrefix(ksp->pc,prefix);
121:   PetscObjectAppendOptionsPrefix((PetscObject)ksp,prefix);
122:   return(0);
123: }

127: /*@C
128:    KSPGetOptionsPrefix - Gets the prefix used for searching for all 
129:    KSP options in the database.

131:    Not Collective

133:    Input Parameters:
134: .  ksp - the Krylov context

136:    Output Parameters:
137: .  prefix - pointer to the prefix string used is returned

139:    Notes: On the fortran side, the user should pass in a string 'prifix' of
140:    sufficient length to hold the prefix.

142:    Level: advanced

144: .keywords: KSP, set, options, prefix, database

146: .seealso: KSPSetOptionsPrefix(), KSPAppendOptionsPrefix()
147: @*/
148: PetscErrorCode  KSPGetOptionsPrefix(KSP ksp,const char *prefix[])
149: {
153:   PetscObjectGetOptionsPrefix((PetscObject)ksp,prefix);
154:   return(0);
155: }

159: /*@
160:    KSPSetFromOptions - Sets KSP options from the options database.
161:    This routine must be called before KSPSetUp() if the user is to be 
162:    allowed to set the Krylov type. 

164:    Collective on KSP

166:    Input Parameters:
167: .  ksp - the Krylov space context

169:    Options Database Keys:
170: +   -ksp_max_it - maximum number of linear iterations
171: .   -ksp_rtol rtol - relative tolerance used in default determination of convergence, i.e.
172:                 if residual norm decreases by this factor than convergence is declared
173: .   -ksp_atol abstol - absolute tolerance used in default convergence test, i.e. if residual 
174:                 norm is less than this then convergence is declared
175: .   -ksp_divtol tol - if residual norm increases by this factor than divergence is declared
176: .   -ksp_converged_use_initial_residual_norm - see KSPDefaultConvergedSetUIRNorm()
177: .   -ksp_converged_use_min_initial_residual_norm - see KSPDefaultConvergedSetUMIRNorm()
178: .   -ksp_norm_type - none - skip norms used in convergence tests (useful only when not using 
179: $                       convergence test (say you always want to run with 5 iterations) to 
180: $                       save on communication overhead
181: $                    preconditioned - default for left preconditioning 
182: $                    unpreconditioned - see KSPSetNormType()
183: $                    natural - see KSPSetNormType()
184: .    -ksp_constant_null_space - assume the operator (matrix) has the constant vector in its null space
185: .    -ksp_test_null_space - tests the null space set with KSPSetNullSpace() to see if it truly is a null space
186: .   -ksp_knoll - compute initial guess by applying the preconditioner to the right hand side
187: .   -ksp_monitor_cancel - cancel all previous convergene monitor routines set
188: .   -ksp_monitor <optional filename> - print residual norm at each iteration
189: .   -ksp_monitor_draw - plot residual norm at each iteration
190: .   -ksp_monitor_solution - plot solution at each iteration
191: -   -ksp_monitor_singular_value - monitor extremem singular values at each iteration

193:    Notes:  
194:    To see all options, run your program with the -help option
195:    or consult the users manual.

197:    Level: beginner

199: .keywords: KSP, set, from, options, database

201: .seealso: 
202: @*/
203: PetscErrorCode  KSPSetFromOptions(KSP ksp)
204: {
205:   PetscErrorCode          ierr;
206:   PetscInt                indx;
207:   char                    type[256], monfilename[PETSC_MAX_PATH_LEN];
208:   PetscViewerASCIIMonitor monviewer;
209:   PetscTruth              flg,flag;
210:   PetscInt                i;

214:   PCSetFromOptions(ksp->pc);

216:   if (!KSPRegisterAllCalled) {KSPRegisterAll(PETSC_NULL);}
217:   PetscOptionsBegin(ksp->comm,ksp->prefix,"Krylov Method (KSP) Options","KSP");
218:     PetscOptionsList("-ksp_type","Krylov method","KSPSetType",KSPList,(char*)(ksp->type_name?ksp->type_name:KSPGMRES),type,256,&flg);
219:     if (flg) {
220:       KSPSetType(ksp,type);
221:     }
222:     /*
223:       Set the type if it was never set.
224:     */
225:     if (!ksp->type_name) {
226:       KSPSetType(ksp,KSPGMRES);
227:     }

229:     PetscOptionsInt("-ksp_max_it","Maximum number of iterations","KSPSetTolerances",ksp->max_it,&ksp->max_it,PETSC_NULL);
230:     PetscOptionsReal("-ksp_rtol","Relative decrease in residual norm","KSPSetTolerances",ksp->rtol,&ksp->rtol,PETSC_NULL);
231:     PetscOptionsReal("-ksp_atol","Absolute value of residual norm","KSPSetTolerances",ksp->abstol,&ksp->abstol,PETSC_NULL);
232:     PetscOptionsReal("-ksp_divtol","Residual norm increase cause divergence","KSPSetTolerances",ksp->divtol,&ksp->divtol,PETSC_NULL);

234:     PetscOptionsName("-ksp_converged_use_initial_residual_norm","Use initial residual residual norm for computing relative convergence","KSPDefaultConvergedSetUIRNorm",&flag);
235:     if (flag) {KSPDefaultConvergedSetUIRNorm(ksp);}
236:     PetscOptionsName("-ksp_converged_use_min_initial_residual_norm","Use minimum of initial residual norm and b for computing relative convergence","KSPDefaultConvergedSetUMIRNorm",&flag);
237:     if (flag) {KSPDefaultConvergedSetUMIRNorm(ksp);}

239:     PetscOptionsTruth("-ksp_knoll","Use preconditioner applied to b for initial guess","KSPSetInitialGuessKnoll",ksp->guess_knoll,
240:                                   &ksp->guess_knoll,PETSC_NULL);

242:     PetscOptionsEList("-ksp_norm_type","KSP Norm type","KSPSetNormType",KSPNormTypes,4,"preconditioned",&indx,&flg);
243:     if (flg) {
244:       if (indx == (PetscInt)KSP_NORM_NO) {
245:         KSPSetConvergenceTest(ksp,KSPSkipConverged,0);
246:       }
247:       KSPSetNormType(ksp,(KSPNormType)indx);
248:     }

250:     PetscOptionsName("-ksp_diagonal_scale","Diagonal scale matrix before building preconditioner","KSPSetDiagonalScale",&flg);
251:     if (flg) {
252:       KSPSetDiagonalScale(ksp,PETSC_TRUE);
253:     }
254:     PetscOptionsName("-ksp_diagonal_scale_fix","Fix diagonaled scaled matrix after solve","KSPSetDiagonalScaleFix",&flg);
255:     if (flg) {
256:       KSPSetDiagonalScaleFix(ksp,PETSC_TRUE);
257:     }


260:     PetscOptionsName("-ksp_constant_null_space","Add constant null space to Krylov solver","KSPSetNullSpace",&flg);
261:     if (flg) {
262:       MatNullSpace nsp;

264:       MatNullSpaceCreate(ksp->comm,PETSC_TRUE,0,0,&nsp);
265:       KSPSetNullSpace(ksp,nsp);
266:       MatNullSpaceDestroy(nsp);
267:     }

269:     /* option is actually checked in KSPSetUp() */
270:     if (ksp->nullsp) {
271:       PetscOptionsName("-ksp_test_null_space","Is provided null space correct","None",&flg);
272:     }

274:     /*
275:       Prints reason for convergence or divergence of each linear solve
276:     */
277:     PetscOptionsName("-ksp_converged_reason","Print reason for converged or diverged","KSPSolve",&flg);
278:     if (flg) {
279:       ksp->printreason = PETSC_TRUE;
280:     }

282:     PetscOptionsName("-ksp_monitor_cancel","Remove any hardwired monitor routines","KSPMonitorCancel",&flg);
283:     /* -----------------------------------------------------------------------*/
284:     /*
285:       Cancels all monitors hardwired into code before call to KSPSetFromOptions()
286:     */
287:     if (flg) {
288:       KSPMonitorCancel(ksp);
289:     }
290:     /*
291:       Prints preconditioned residual norm at each iteration
292:     */
293:     PetscOptionsString("-ksp_monitor","Monitor preconditioned residual norm","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
294:     if (flg) {
295:       PetscViewerASCIIMonitorCreate(ksp->comm,monfilename,0,&monviewer);
296:       KSPMonitorSet(ksp,KSPMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
297:     }
298:     /*
299:       Plots the vector solution 
300:     */
301:     PetscOptionsName("-ksp_monitor_solution","Monitor solution graphically","KSPMonitorSet",&flg);
302:     if (flg) {
303:       KSPMonitorSet(ksp,KSPMonitorSolution,PETSC_NULL,PETSC_NULL);
304:     }
305:     /*
306:       Prints preconditioned and true residual norm at each iteration
307:     */
308:     PetscOptionsString("-ksp_monitor_true_residual","Monitor preconditioned residual norm","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
309:     if (flg) {
310:       PetscViewerASCIIMonitorCreate(ksp->comm,monfilename,0,&monviewer);
311:       KSPMonitorSet(ksp,KSPMonitorTrueResidualNorm,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
312:     }
313:     /*
314:       Prints extreme eigenvalue estimates at each iteration
315:     */
316:     PetscOptionsString("-ksp_monitor_singular_value","Monitor singular values","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
317:     if (flg) {
318:       KSPSetComputeSingularValues(ksp,PETSC_TRUE);
319:       PetscViewerASCIIMonitorCreate(ksp->comm,monfilename,0,&monviewer);
320:       KSPMonitorSet(ksp,KSPMonitorSingularValue,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
321:     }
322:     /*
323:       Prints preconditioned residual norm with fewer digits
324:     */
325:     PetscOptionsString("-ksp_monitor_short","Monitor preconditioned residual norm with fewer digits","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
326:     if (flg) {
327:       PetscViewerASCIIMonitorCreate(ksp->comm,monfilename,0,&monviewer);
328:       KSPMonitorSet(ksp,KSPMonitorDefaultShort,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
329:     }
330:     /*
331:       Graphically plots preconditioned residual norm
332:     */
333:     PetscOptionsName("-ksp_monitor_draw","Monitor graphically preconditioned residual norm","KSPMonitorSet",&flg);
334:     if (flg) {
335:       KSPMonitorSet(ksp,KSPMonitorLG,PETSC_NULL,PETSC_NULL);
336:     }
337:     /*
338:       Graphically plots preconditioned and true residual norm
339:     */
340:     PetscOptionsName("-ksp_monitor_draw_true_residual","Monitor graphically true residual norm","KSPMonitorSet",&flg);
341:     if (flg){
342:       KSPMonitorSet(ksp,KSPMonitorLGTrueResidualNorm,PETSC_NULL,PETSC_NULL);
343:     }

345:     /* -----------------------------------------------------------------------*/

347:     PetscOptionsTruthGroupBegin("-ksp_left_pc","Use left preconditioning","KSPSetPreconditionerSide",&flg);
348:     if (flg) { KSPSetPreconditionerSide(ksp,PC_LEFT); }
349:     PetscOptionsTruthGroup("-ksp_right_pc","Use right preconditioning","KSPSetPreconditionerSide",&flg);
350:     if (flg) { KSPSetPreconditionerSide(ksp,PC_RIGHT);}
351:     PetscOptionsTruthGroupEnd("-ksp_symmetric_pc","Use symmetric (factorized) preconditioning","KSPSetPreconditionerSide",&flg);
352:     if (flg) { KSPSetPreconditionerSide(ksp,PC_SYMMETRIC);}

354:     PetscOptionsName("-ksp_compute_singularvalues","Compute singular values of preconditioned operator","KSPSetComputeSingularValues",&flg);
355:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
356:     PetscOptionsName("-ksp_compute_eigenvalues","Compute eigenvalues of preconditioned operator","KSPSetComputeSingularValues",&flg);
357:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
358:     PetscOptionsName("-ksp_plot_eigenvalues","Scatter plot extreme eigenvalues","KSPSetComputeSingularValues",&flg);
359:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }

361:     for(i = 0; i < numberofsetfromoptions; i++) {
362:       (*othersetfromoptions[i])(ksp);
363:     }

365:     if (ksp->ops->setfromoptions) {
366:       (*ksp->ops->setfromoptions)(ksp);
367:     }
368:     PetscOptionsName("-ksp_view","View linear solver parameters","KSPView",&flg);
369:   PetscOptionsEnd();
370:   return(0);
371: }