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_check_norm_iteration it - do not compute residual norm until iteration number it (does compute at 0th iteration)
185: $ works only for PCBCGS and and PCCG
186: . -ksp_constant_null_space - assume the operator (matrix) has the constant vector in its null space
187: . -ksp_test_null_space - tests the null space set with KSPSetNullSpace() to see if it truly is a null space
188: . -ksp_knoll - compute initial guess by applying the preconditioner to the right hand side
189: . -ksp_monitor_cancel - cancel all previous convergene monitor routines set
190: . -ksp_monitor <optional filename> - print residual norm at each iteration
191: . -ksp_monitor_draw - plot residual norm at each iteration
192: . -ksp_monitor_solution - plot solution at each iteration
193: - -ksp_monitor_singular_value - monitor extremem singular values at each iteration
195: Notes:
196: To see all options, run your program with the -help option
197: or consult the users manual.
199: Level: beginner
201: .keywords: KSP, set, from, options, database
203: .seealso:
204: @*/
205: PetscErrorCode KSPSetFromOptions(KSP ksp)
206: {
207: PetscErrorCode ierr;
208: PetscInt indx;
209: const char *convtests[] = {"default","skip"};
210: char type[256], monfilename[PETSC_MAX_PATH_LEN];
211: PetscViewerASCIIMonitor monviewer;
212: PetscTruth flg,flag;
213: PetscInt i;
214: void *ctx;
218: PCSetFromOptions(ksp->pc);
220: if (!KSPRegisterAllCalled) {KSPRegisterAll(PETSC_NULL);}
221: PetscOptionsBegin(((PetscObject)ksp)->comm,((PetscObject)ksp)->prefix,"Krylov Method (KSP) Options","KSP");
222: PetscOptionsList("-ksp_type","Krylov method","KSPSetType",KSPList,(char*)(((PetscObject)ksp)->type_name?((PetscObject)ksp)->type_name:KSPGMRES),type,256,&flg);
223: if (flg) {
224: KSPSetType(ksp,type);
225: }
226: /*
227: Set the type if it was never set.
228: */
229: if (!((PetscObject)ksp)->type_name) {
230: KSPSetType(ksp,KSPGMRES);
231: }
233: PetscOptionsInt("-ksp_max_it","Maximum number of iterations","KSPSetTolerances",ksp->max_it,&ksp->max_it,PETSC_NULL);
234: PetscOptionsReal("-ksp_rtol","Relative decrease in residual norm","KSPSetTolerances",ksp->rtol,&ksp->rtol,PETSC_NULL);
235: PetscOptionsReal("-ksp_atol","Absolute value of residual norm","KSPSetTolerances",ksp->abstol,&ksp->abstol,PETSC_NULL);
236: PetscOptionsReal("-ksp_divtol","Residual norm increase cause divergence","KSPSetTolerances",ksp->divtol,&ksp->divtol,PETSC_NULL);
238: PetscOptionsName("-ksp_converged_use_initial_residual_norm","Use initial residual residual norm for computing relative convergence","KSPDefaultConvergedSetUIRNorm",&flag);
239: if (flag) {KSPDefaultConvergedSetUIRNorm(ksp);}
240: PetscOptionsName("-ksp_converged_use_min_initial_residual_norm","Use minimum of initial residual norm and b for computing relative convergence","KSPDefaultConvergedSetUMIRNorm",&flag);
241: if (flag) {KSPDefaultConvergedSetUMIRNorm(ksp);}
243: PetscOptionsTruth("-ksp_knoll","Use preconditioner applied to b for initial guess","KSPSetInitialGuessKnoll",ksp->guess_knoll,
244: &ksp->guess_knoll,PETSC_NULL);
246: PetscOptionsEList("-ksp_convergence_test","Convergence test","KSPSetConvergenceTest",convtests,2,"default",&indx,&flg);
247: if (flg) {
248: switch (indx) {
249: case 0:
250: KSPDefaultConvergedCreate(&ctx);
251: KSPSetConvergenceTest(ksp,KSPDefaultConverged,ctx,KSPDefaultConvergedDestroy);
252: break;
253: case 1: KSPSetConvergenceTest(ksp,KSPSkipConverged,PETSC_NULL,PETSC_NULL); break;
254: }
255: }
257: PetscOptionsEList("-ksp_norm_type","KSP Norm type","KSPSetNormType",KSPNormTypes,4,"preconditioned",&indx,&flg);
258: if (flg) { KSPSetNormType(ksp,(KSPNormType)indx); }
260: PetscOptionsInt("-ksp_check_norm_iteration","First iteration to compute residual norm","KSPSetCheckNormIteration",ksp->chknorm,&ksp->chknorm,PETSC_NULL);
262: PetscOptionsName("-ksp_diagonal_scale","Diagonal scale matrix before building preconditioner","KSPSetDiagonalScale",&flg);
263: if (flg) {
264: KSPSetDiagonalScale(ksp,PETSC_TRUE);
265: }
266: PetscOptionsName("-ksp_diagonal_scale_fix","Fix diagonaled scaled matrix after solve","KSPSetDiagonalScaleFix",&flg);
267: if (flg) {
268: KSPSetDiagonalScaleFix(ksp,PETSC_TRUE);
269: }
272: PetscOptionsName("-ksp_constant_null_space","Add constant null space to Krylov solver","KSPSetNullSpace",&flg);
273: if (flg) {
274: MatNullSpace nsp;
276: MatNullSpaceCreate(((PetscObject)ksp)->comm,PETSC_TRUE,0,0,&nsp);
277: KSPSetNullSpace(ksp,nsp);
278: MatNullSpaceDestroy(nsp);
279: }
281: /* option is actually checked in KSPSetUp() */
282: if (ksp->nullsp) {
283: PetscOptionsName("-ksp_test_null_space","Is provided null space correct","None",&flg);
284: }
286: /*
287: Prints reason for convergence or divergence of each linear solve
288: */
289: PetscOptionsName("-ksp_converged_reason","Print reason for converged or diverged","KSPSolve",&flg);
290: if (flg) {
291: ksp->printreason = PETSC_TRUE;
292: }
294: PetscOptionsName("-ksp_monitor_cancel","Remove any hardwired monitor routines","KSPMonitorCancel",&flg);
295: /* -----------------------------------------------------------------------*/
296: /*
297: Cancels all monitors hardwired into code before call to KSPSetFromOptions()
298: */
299: if (flg) {
300: KSPMonitorCancel(ksp);
301: }
302: /*
303: Prints preconditioned residual norm at each iteration
304: */
305: PetscOptionsString("-ksp_monitor","Monitor preconditioned residual norm","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
306: if (flg) {
307: PetscViewerASCIIMonitorCreate(((PetscObject)ksp)->comm,monfilename,0,&monviewer);
308: KSPMonitorSet(ksp,KSPMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
309: }
310: /*
311: Plots the vector solution
312: */
313: PetscOptionsName("-ksp_monitor_solution","Monitor solution graphically","KSPMonitorSet",&flg);
314: if (flg) {
315: KSPMonitorSet(ksp,KSPMonitorSolution,PETSC_NULL,PETSC_NULL);
316: }
317: /*
318: Prints preconditioned and true residual norm at each iteration
319: */
320: PetscOptionsString("-ksp_monitor_true_residual","Monitor preconditioned residual norm","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
321: if (flg) {
322: PetscViewerASCIIMonitorCreate(((PetscObject)ksp)->comm,monfilename,0,&monviewer);
323: KSPMonitorSet(ksp,KSPMonitorTrueResidualNorm,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
324: }
325: /*
326: Prints extreme eigenvalue estimates at each iteration
327: */
328: PetscOptionsString("-ksp_monitor_singular_value","Monitor singular values","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
329: if (flg) {
330: KSPSetComputeSingularValues(ksp,PETSC_TRUE);
331: PetscViewerASCIIMonitorCreate(((PetscObject)ksp)->comm,monfilename,0,&monviewer);
332: KSPMonitorSet(ksp,KSPMonitorSingularValue,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
333: }
334: /*
335: Prints preconditioned residual norm with fewer digits
336: */
337: PetscOptionsString("-ksp_monitor_short","Monitor preconditioned residual norm with fewer digits","KSPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
338: if (flg) {
339: PetscViewerASCIIMonitorCreate(((PetscObject)ksp)->comm,monfilename,0,&monviewer);
340: KSPMonitorSet(ksp,KSPMonitorDefaultShort,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
341: }
342: /*
343: Graphically plots preconditioned residual norm
344: */
345: PetscOptionsName("-ksp_monitor_draw","Monitor graphically preconditioned residual norm","KSPMonitorSet",&flg);
346: if (flg) {
347: KSPMonitorSet(ksp,KSPMonitorLG,PETSC_NULL,PETSC_NULL);
348: }
349: /*
350: Graphically plots preconditioned and true residual norm
351: */
352: PetscOptionsName("-ksp_monitor_draw_true_residual","Monitor graphically true residual norm","KSPMonitorSet",&flg);
353: if (flg){
354: KSPMonitorSet(ksp,KSPMonitorLGTrueResidualNorm,PETSC_NULL,PETSC_NULL);
355: }
357: /* -----------------------------------------------------------------------*/
359: PetscOptionsTruthGroupBegin("-ksp_left_pc","Use left preconditioning","KSPSetPreconditionerSide",&flg);
360: if (flg) { KSPSetPreconditionerSide(ksp,PC_LEFT); }
361: PetscOptionsTruthGroup("-ksp_right_pc","Use right preconditioning","KSPSetPreconditionerSide",&flg);
362: if (flg) { KSPSetPreconditionerSide(ksp,PC_RIGHT);}
363: PetscOptionsTruthGroupEnd("-ksp_symmetric_pc","Use symmetric (factorized) preconditioning","KSPSetPreconditionerSide",&flg);
364: if (flg) { KSPSetPreconditionerSide(ksp,PC_SYMMETRIC);}
366: PetscOptionsName("-ksp_compute_singularvalues","Compute singular values of preconditioned operator","KSPSetComputeSingularValues",&flg);
367: if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
368: PetscOptionsName("-ksp_compute_eigenvalues","Compute eigenvalues of preconditioned operator","KSPSetComputeSingularValues",&flg);
369: if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
370: PetscOptionsName("-ksp_plot_eigenvalues","Scatter plot extreme eigenvalues","KSPSetComputeSingularValues",&flg);
371: if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
373: for(i = 0; i < numberofsetfromoptions; i++) {
374: (*othersetfromoptions[i])(ksp);
375: }
377: if (ksp->ops->setfromoptions) {
378: (*ksp->ops->setfromoptions)(ksp);
379: }
380: PetscOptionsName("-ksp_view","View linear solver parameters","KSPView",&flg);
381: PetscOptionsEnd();
382: return(0);
383: }