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: }