Actual source code: itcl.c
petsc-3.15.0 2021-04-05
2: /*
3: Code for setting KSP options from the options database.
4: */
6: #include <petsc/private/kspimpl.h>
7: #include <petscdraw.h>
9: /*@C
10: KSPSetOptionsPrefix - Sets the prefix used for searching for all
11: KSP options in the database.
13: Logically Collective on ksp
15: Input Parameters:
16: + ksp - the Krylov context
17: - prefix - the prefix string to prepend to all KSP option requests
19: Notes:
20: A hyphen (-) must NOT be given at the beginning of the prefix name.
21: The first character of all runtime options is AUTOMATICALLY the
22: hyphen.
24: For example, to distinguish between the runtime options for two
25: different KSP contexts, one could call
26: .vb
27: KSPSetOptionsPrefix(ksp1,"sys1_")
28: KSPSetOptionsPrefix(ksp2,"sys2_")
29: .ve
31: This would enable use of different options for each system, such as
32: .vb
33: -sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3
34: -sys2_ksp_type bcgs -sys2_ksp_rtol 1.e-4
35: .ve
37: Level: advanced
39: .seealso: KSPAppendOptionsPrefix(), KSPGetOptionsPrefix()
40: @*/
41: PetscErrorCode KSPSetOptionsPrefix(KSP ksp,const char prefix[])
42: {
47: if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
48: PCSetOptionsPrefix(ksp->pc,prefix);
49: PetscObjectSetOptionsPrefix((PetscObject)ksp,prefix);
50: return(0);
51: }
53: /*@C
54: KSPAppendOptionsPrefix - Appends to the prefix used for searching for all
55: KSP options in the database.
57: Logically Collective on ksp
59: Input Parameters:
60: + ksp - the Krylov context
61: - prefix - the prefix string to prepend to all KSP option requests
63: Notes:
64: A hyphen (-) must NOT be given at the beginning of the prefix name.
65: The first character of all runtime options is AUTOMATICALLY the hyphen.
67: Level: advanced
69: .seealso: KSPSetOptionsPrefix(), KSPGetOptionsPrefix()
70: @*/
71: PetscErrorCode KSPAppendOptionsPrefix(KSP ksp,const char prefix[])
72: {
77: if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
78: PCAppendOptionsPrefix(ksp->pc,prefix);
79: PetscObjectAppendOptionsPrefix((PetscObject)ksp,prefix);
80: return(0);
81: }
83: /*@
84: KSPSetUseFischerGuess - Use the Paul Fischer algorithm
86: Logically Collective on ksp
88: Input Parameters:
89: + ksp - the Krylov context
90: . model - use model 1, model 2 or any other number to turn it off
91: - size - size of subspace used to generate initial guess
93: Options Database:
94: . -ksp_fischer_guess <model,size> - uses the Fischer initial guess generator for repeated linear solves
96: Level: advanced
98: .seealso: KSPSetOptionsPrefix(), KSPAppendOptionsPrefix(), KSPSetUseFischerGuess(), KSPSetGuess(), KSPGetGuess()
99: @*/
100: PetscErrorCode KSPSetUseFischerGuess(KSP ksp,PetscInt model,PetscInt size)
101: {
102: KSPGuess guess;
109: KSPGetGuess(ksp,&guess);
110: KSPGuessSetType(guess,KSPGUESSFISCHER);
111: KSPGuessFischerSetModel(guess,model,size);
112: return(0);
113: }
115: /*@
116: KSPSetGuess - Set the initial guess object
118: Logically Collective on ksp
120: Input Parameters:
121: + ksp - the Krylov context
122: - guess - the object created with KSPGuessCreate()
124: Level: advanced
126: Notes:
127: this allows a single KSP to be used with several different initial guess generators (likely for different linear
128: solvers, see KSPSetPC()).
130: This increases the reference count of the guess object, you must destroy the object with KSPGuessDestroy()
131: before the end of the program.
133: .seealso: KSPSetOptionsPrefix(), KSPAppendOptionsPrefix(), KSPSetUseFischerGuess(), KSPGetGuess()
134: @*/
135: PetscErrorCode KSPSetGuess(KSP ksp,KSPGuess guess)
136: {
142: PetscObjectReference((PetscObject)guess);
143: KSPGuessDestroy(&ksp->guess);
144: ksp->guess = guess;
145: ksp->guess->ksp = ksp;
146: return(0);
147: }
149: /*@
150: KSPGetGuess - Gets the initial guess generator for the KSP.
152: Not Collective
154: Input Parameters:
155: . ksp - the Krylov context
157: Output Parameters:
158: . guess - the object
160: Level: developer
162: .seealso: KSPSetOptionsPrefix(), KSPAppendOptionsPrefix(), KSPSetUseFischerGuess(), KSPSetGuess()
163: @*/
164: PetscErrorCode KSPGetGuess(KSP ksp,KSPGuess *guess)
165: {
171: if (!ksp->guess) {
172: const char* prefix;
174: KSPGuessCreate(PetscObjectComm((PetscObject)ksp),&ksp->guess);
175: PetscObjectGetOptionsPrefix((PetscObject)ksp,&prefix);
176: if (prefix) {
177: PetscObjectSetOptionsPrefix((PetscObject)ksp->guess,prefix);
178: }
179: ksp->guess->ksp = ksp;
180: }
181: *guess = ksp->guess;
182: return(0);
183: }
185: /*@C
186: KSPGetOptionsPrefix - Gets the prefix used for searching for all
187: KSP options in the database.
189: Not Collective
191: Input Parameters:
192: . ksp - the Krylov context
194: Output Parameters:
195: . prefix - pointer to the prefix string used is returned
197: Notes:
198: On the fortran side, the user should pass in a string 'prefix' of
199: sufficient length to hold the prefix.
201: Level: advanced
203: .seealso: KSPSetOptionsPrefix(), KSPAppendOptionsPrefix()
204: @*/
205: PetscErrorCode KSPGetOptionsPrefix(KSP ksp,const char *prefix[])
206: {
211: PetscObjectGetOptionsPrefix((PetscObject)ksp,prefix);
212: return(0);
213: }
215: static PetscErrorCode PetscViewerAndFormatCreate_Internal(PetscViewer viewer, PetscViewerFormat format, void *ctx, PetscViewerAndFormat **vf)
216: {
220: PetscViewerAndFormatCreate(viewer, format, vf);
221: (*vf)->data = ctx;
222: return(0);
223: }
225: /*@C
226: KSPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type indicated by the user
228: Collective on ksp
230: Input Parameters:
231: + ksp - KSP object you wish to monitor
232: . opt - the command line option for this monitor
233: . name - the monitor type one is seeking
234: - ctx - An optional user context for the monitor, or NULL
236: Level: developer
238: .seealso: PetscOptionsGetViewer(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
239: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
240: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
241: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
242: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
243: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
244: PetscOptionsFList(), PetscOptionsEList()
245: @*/
246: PetscErrorCode KSPMonitorSetFromOptions(KSP ksp, const char opt[], const char name[], void *ctx)
247: {
248: PetscErrorCode (*mfunc)(KSP, PetscInt, PetscReal, void *);
249: PetscErrorCode (*cfunc)(PetscViewer, PetscViewerFormat, void *, PetscViewerAndFormat **);
250: PetscErrorCode (*dfunc)(PetscViewerAndFormat **);
251: PetscViewerAndFormat *vf;
252: PetscViewer viewer;
253: PetscViewerFormat format;
254: PetscViewerType vtype;
255: char key[PETSC_MAX_PATH_LEN];
256: PetscBool all, flg;
257: const char *prefix = NULL;
258: PetscErrorCode ierr;
261: PetscStrcmp(opt, "-all_ksp_monitor", &all);
262: if (!all) {PetscObjectGetOptionsPrefix((PetscObject) ksp, &prefix);}
263: PetscOptionsGetViewer(PetscObjectComm((PetscObject) ksp), ((PetscObject) ksp)->options, prefix, opt, &viewer, &format, &flg);
264: if (!flg) return(0);
266: PetscViewerGetType(viewer, &vtype);
267: KSPMonitorMakeKey_Internal(name, vtype, format, key);
268: PetscFunctionListFind(KSPMonitorList, key, &mfunc);
269: PetscFunctionListFind(KSPMonitorCreateList, key, &cfunc);
270: PetscFunctionListFind(KSPMonitorDestroyList, key, &dfunc);
271: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
272: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
274: (*cfunc)(viewer, format, ctx, &vf);
275: PetscObjectDereference((PetscObject) viewer);
276: KSPMonitorSet(ksp, mfunc, vf, (PetscErrorCode (*)(void **)) dfunc);
277: return(0);
278: }
280: /*@
281: KSPSetFromOptions - Sets KSP options from the options database.
282: This routine must be called before KSPSetUp() if the user is to be
283: allowed to set the Krylov type.
285: Collective on ksp
287: Input Parameters:
288: . ksp - the Krylov space context
290: Options Database Keys:
291: + -ksp_max_it - maximum number of linear iterations
292: . -ksp_rtol rtol - relative tolerance used in default determination of convergence, i.e.
293: if residual norm decreases by this factor than convergence is declared
294: . -ksp_atol abstol - absolute tolerance used in default convergence test, i.e. if residual
295: norm is less than this then convergence is declared
296: . -ksp_divtol tol - if residual norm increases by this factor than divergence is declared
297: . -ksp_converged_use_initial_residual_norm - see KSPConvergedDefaultSetUIRNorm()
298: . -ksp_converged_use_min_initial_residual_norm - see KSPConvergedDefaultSetUMIRNorm()
299: . -ksp_converged_maxits - see KSPConvergedDefaultSetConvergedMaxits()
300: . -ksp_norm_type - none - skip norms used in convergence tests (useful only when not using
301: convergence test (say you always want to run with 5 iterations) to
302: save on communication overhead
303: preconditioned - default for left preconditioning
304: unpreconditioned - see KSPSetNormType()
305: natural - see KSPSetNormType()
306: . -ksp_check_norm_iteration it - do not compute residual norm until iteration number it (does compute at 0th iteration)
307: works only for PCBCGS, PCIBCGS and and PCCG
308: . -ksp_lag_norm - compute the norm of the residual for the ith iteration on the i+1 iteration; this means that one can use
309: the norm of the residual for convergence test WITHOUT an extra MPI_Allreduce() limiting global synchronizations.
310: This will require 1 more iteration of the solver than usual.
311: . -ksp_guess_type - Type of initial guess generator for repeated linear solves
312: . -ksp_fischer_guess <model,size> - uses the Fischer initial guess generator for repeated linear solves
313: . -ksp_constant_null_space - assume the operator (matrix) has the constant vector in its null space
314: . -ksp_test_null_space - tests the null space set with MatSetNullSpace() to see if it truly is a null space
315: . -ksp_knoll - compute initial guess by applying the preconditioner to the right hand side
316: . -ksp_monitor_cancel - cancel all previous convergene monitor routines set
317: . -ksp_monitor - print residual norm at each iteration
318: . -ksp_monitor draw::draw_lg - plot residual norm at each iteration
319: . -ksp_monitor_true_residual - print true residual norm at each iteration
320: . -all_ksp_monitor <optional filename> - print residual norm at each iteration for ALL KSP solves, regardless of their prefix. This is
321: useful for PCFIELDSPLIT, PCMG, etc that have inner solvers and you wish to track the convergence of all the solvers
322: . -ksp_monitor_solution [ascii binary or draw][:filename][:format option] - plot solution at each iteration
323: . -ksp_monitor_singular_value - monitor extreme singular values at each iteration
324: . -ksp_converged_reason - view the convergence state at the end of the solve
325: . -ksp_use_explicittranspose - transpose the system explicitly in KSPSolveTranspose
326: - -ksp_converged_rate - view the convergence rate at the end of the solve
328: Notes:
329: To see all options, run your program with the -help option
330: or consult Users-Manual: ch_ksp
332: Level: beginner
334: .seealso: KSPSetOptionsPrefix(), KSPResetFromOptions(), KSPSetUseFischerGuess()
336: @*/
337: PetscErrorCode KSPSetFromOptions(KSP ksp)
338: {
339: const char *convtests[]={"default","skip","lsqr"},*prefix;
340: char type[256],guesstype[256],monfilename[PETSC_MAX_PATH_LEN];
341: PetscBool flg,flag,reuse,set;
342: PetscInt indx,model[2]={0,0},nmax;
343: KSPNormType normtype;
344: PCSide pcside;
345: void *ctx;
346: MPI_Comm comm;
351: PetscObjectGetComm((PetscObject) ksp, &comm);
352: PetscObjectGetOptionsPrefix((PetscObject) ksp, &prefix);
353: if (!ksp->skippcsetfromoptions) {
354: if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
355: PCSetFromOptions(ksp->pc);
356: }
358: KSPRegisterAll();
359: PetscObjectOptionsBegin((PetscObject)ksp);
360: PetscOptionsFList("-ksp_type","Krylov method","KSPSetType",KSPList,(char*)(((PetscObject)ksp)->type_name ? ((PetscObject)ksp)->type_name : KSPGMRES),type,256,&flg);
361: if (flg) {
362: KSPSetType(ksp,type);
363: }
364: /*
365: Set the type if it was never set.
366: */
367: if (!((PetscObject)ksp)->type_name) {
368: KSPSetType(ksp,KSPGMRES);
369: }
371: KSPResetViewers(ksp);
373: /* Cancels all monitors hardwired into code before call to KSPSetFromOptions() */
374: PetscOptionsBool("-ksp_monitor_cancel","Remove any hardwired monitor routines","KSPMonitorCancel",PETSC_FALSE,&flg,&set);
375: if (set && flg) {KSPMonitorCancel(ksp);}
376: KSPMonitorSetFromOptions(ksp, "-ksp_monitor", "preconditioned_residual", NULL);
377: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_short", "preconditioned_residual_short", NULL);
378: KSPMonitorSetFromOptions(ksp, "-all_ksp_monitor", "preconditioned_residual", NULL);
379: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_range", "preconditioned_residual_range", NULL);
380: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_true_residual", "true_residual", NULL);
381: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_max", "true_residual_max", NULL);
382: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_solution", "solution", NULL);
383: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_singular_value", "singular_value", ksp);
384: KSPMonitorSetFromOptions(ksp, "-ksp_monitor_error", "error", ksp);
385: PetscOptionsBool("-ksp_monitor_pause_final", "Pauses all draw monitors at the final iterate", "KSPMonitorPauseFinal_Internal", PETSC_FALSE, &ksp->pauseFinal, NULL);
387: PetscObjectTypeCompare((PetscObject)ksp,KSPPREONLY,&flg);
388: if (flg) {
389: KSPGetReusePreconditioner(ksp,&reuse);
390: PetscOptionsBool("-ksp_reuse_preconditioner","Use initial preconditioner and don't ever compute a new one","KSPReusePreconditioner",reuse,&reuse,NULL);
391: KSPSetReusePreconditioner(ksp,reuse);
392: PetscOptionsBool("-ksp_error_if_not_converged","Generate error if solver does not converge","KSPSetErrorIfNotConverged",ksp->errorifnotconverged,&ksp->errorifnotconverged,NULL);
393: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view",&ksp->viewer, &ksp->format,&ksp->view);
394: flg = PETSC_FALSE;
395: PetscOptionsBool("-ksp_converged_reason_view_cancel","Cancel all the converged reason view functions set using KSPConvergedReasonViewSet","KSPConvergedReasonViewCancel",PETSC_FALSE,&flg,&set);
396: if (set && flg) {
397: KSPConvergedReasonViewCancel(ksp);
398: }
399: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_mat",&ksp->viewerMat,&ksp->formatMat,&ksp->viewMat);
400: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_pmat",&ksp->viewerPMat,&ksp->formatPMat,&ksp->viewPMat);
401: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_rhs",&ksp->viewerRhs,&ksp->formatRhs,&ksp->viewRhs);
402: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_solution",&ksp->viewerSol,&ksp->formatSol,&ksp->viewSol);
403: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_mat_explicit",&ksp->viewerMatExp,&ksp->formatMatExp,&ksp->viewMatExp);
404: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_final_residual",&ksp->viewerFinalRes,&ksp->formatFinalRes,&ksp->viewFinalRes);
405: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_preconditioned_operator_explicit",&ksp->viewerPOpExp,&ksp->formatPOpExp,&ksp->viewPOpExp);
406: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_diagonal_scale",&ksp->viewerDScale,&ksp->formatDScale,&ksp->viewDScale);
408: KSPGetDiagonalScale(ksp,&flag);
409: PetscOptionsBool("-ksp_diagonal_scale","Diagonal scale matrix before building preconditioner","KSPSetDiagonalScale",flag,&flag,&flg);
410: if (flg) {
411: KSPSetDiagonalScale(ksp,flag);
412: }
413: KSPGetDiagonalScaleFix(ksp,&flag);
414: PetscOptionsBool("-ksp_diagonal_scale_fix","Fix diagonally scaled matrix after solve","KSPSetDiagonalScaleFix",flag,&flag,&flg);
415: if (flg) {
416: KSPSetDiagonalScaleFix(ksp,flag);
417: }
418: nmax = ksp->nmax;
419: PetscOptionsDeprecated("-ksp_matsolve_block_size","-ksp_matsolve_batch_size","3.15",NULL);
420: PetscOptionsInt("-ksp_matsolve_batch_size", "Maximum number of columns treated simultaneously", "KSPSetMatSolveBatchSize", nmax, &nmax, &flg);
421: if (flg) {
422: KSPSetMatSolveBatchSize(ksp, nmax);
423: }
424: goto skipoptions;
425: }
427: PetscOptionsInt("-ksp_max_it","Maximum number of iterations","KSPSetTolerances",ksp->max_it,&ksp->max_it,NULL);
428: PetscOptionsReal("-ksp_rtol","Relative decrease in residual norm","KSPSetTolerances",ksp->rtol,&ksp->rtol,NULL);
429: PetscOptionsReal("-ksp_atol","Absolute value of residual norm","KSPSetTolerances",ksp->abstol,&ksp->abstol,NULL);
430: PetscOptionsReal("-ksp_divtol","Residual norm increase cause divergence","KSPSetTolerances",ksp->divtol,&ksp->divtol,NULL);
432: PetscOptionsBool("-ksp_converged_use_initial_residual_norm","Use initial residual norm for computing relative convergence","KSPConvergedDefaultSetUIRNorm",PETSC_FALSE,&flag,&set);
433: if (set && flag) {KSPConvergedDefaultSetUIRNorm(ksp);}
434: PetscOptionsBool("-ksp_converged_use_min_initial_residual_norm","Use minimum of initial residual norm and b for computing relative convergence","KSPConvergedDefaultSetUMIRNorm",PETSC_FALSE,&flag,&set);
435: if (set && flag) {KSPConvergedDefaultSetUMIRNorm(ksp);}
436: PetscOptionsBool("-ksp_converged_maxits","Declare convergence if the maximum number of iterations is reached","KSPConvergedDefaultSetConvergedMaxits",PETSC_FALSE,&flag,&set);
437: if (set) {KSPConvergedDefaultSetConvergedMaxits(ksp,flag);}
438: PetscOptionsBool("-ksp_initial_guess_nonzero","Use the contents of the solution vector for initial guess","KSPSetInitialNonzero",ksp->guess_zero ? PETSC_FALSE : PETSC_TRUE,&flag,&flg);
439: if (flg) {
440: KSPSetInitialGuessNonzero(ksp,flag);
441: }
442: KSPGetReusePreconditioner(ksp,&reuse);
443: PetscOptionsBool("-ksp_reuse_preconditioner","Use initial preconditioner and don't ever compute a new one","KSPReusePreconditioner",reuse,&reuse,NULL);
444: KSPSetReusePreconditioner(ksp,reuse);
446: PetscOptionsBool("-ksp_knoll","Use preconditioner applied to b for initial guess","KSPSetInitialGuessKnoll",ksp->guess_knoll,&ksp->guess_knoll,NULL);
447: PetscOptionsBool("-ksp_error_if_not_converged","Generate error if solver does not converge","KSPSetErrorIfNotConverged",ksp->errorifnotconverged,&ksp->errorifnotconverged,NULL);
448: PetscOptionsFList("-ksp_guess_type","Initial guess in Krylov method",NULL,KSPGuessList,NULL,guesstype,256,&flg);
449: if (flg) {
450: KSPGetGuess(ksp,&ksp->guess);
451: KSPGuessSetType(ksp->guess,guesstype);
452: KSPGuessSetFromOptions(ksp->guess);
453: } else { /* old option for KSP */
454: nmax = 2;
455: PetscOptionsIntArray("-ksp_fischer_guess","Use Paul Fischer's algorithm for initial guess","KSPSetUseFischerGuess",model,&nmax,&flag);
456: if (flag) {
457: if (nmax != 2) SETERRQ(comm,PETSC_ERR_ARG_OUTOFRANGE,"Must pass in model,size as arguments");
458: KSPSetUseFischerGuess(ksp,model[0],model[1]);
459: }
460: }
462: PetscOptionsEList("-ksp_convergence_test","Convergence test","KSPSetConvergenceTest",convtests,3,"default",&indx,&flg);
463: if (flg) {
464: switch (indx) {
465: case 0:
466: KSPConvergedDefaultCreate(&ctx);
467: KSPSetConvergenceTest(ksp,KSPConvergedDefault,ctx,KSPConvergedDefaultDestroy);
468: break;
469: case 1:
470: KSPSetConvergenceTest(ksp,KSPConvergedSkip,NULL,NULL);
471: break;
472: case 2:
473: KSPConvergedDefaultCreate(&ctx);
474: KSPSetConvergenceTest(ksp,KSPLSQRConvergedDefault,ctx,KSPConvergedDefaultDestroy);
475: break;
476: }
477: }
479: KSPSetUpNorms_Private(ksp,PETSC_FALSE,&normtype,NULL);
480: PetscOptionsEnum("-ksp_norm_type","KSP Norm type","KSPSetNormType",KSPNormTypes,(PetscEnum)normtype,(PetscEnum*)&normtype,&flg);
481: if (flg) { KSPSetNormType(ksp,normtype); }
483: PetscOptionsInt("-ksp_check_norm_iteration","First iteration to compute residual norm","KSPSetCheckNormIteration",ksp->chknorm,&ksp->chknorm,NULL);
485: PetscOptionsBool("-ksp_lag_norm","Lag the calculation of the residual norm","KSPSetLagNorm",ksp->lagnorm,&flag,&flg);
486: if (flg) {
487: KSPSetLagNorm(ksp,flag);
488: }
490: KSPGetDiagonalScale(ksp,&flag);
491: PetscOptionsBool("-ksp_diagonal_scale","Diagonal scale matrix before building preconditioner","KSPSetDiagonalScale",flag,&flag,&flg);
492: if (flg) {
493: KSPSetDiagonalScale(ksp,flag);
494: }
495: KSPGetDiagonalScaleFix(ksp,&flag);
496: PetscOptionsBool("-ksp_diagonal_scale_fix","Fix diagonally scaled matrix after solve","KSPSetDiagonalScaleFix",flag,&flag,&flg);
497: if (flg) {
498: KSPSetDiagonalScaleFix(ksp,flag);
499: }
501: PetscOptionsBool("-ksp_constant_null_space","Add constant null space to Krylov solver matrix","MatSetNullSpace",PETSC_FALSE,&flg,&set);
502: if (set && flg) {
503: MatNullSpace nsp;
504: Mat Amat = NULL;
506: MatNullSpaceCreate(comm,PETSC_TRUE,0,NULL,&nsp);
507: if (ksp->pc) { PCGetOperators(ksp->pc,&Amat,NULL); }
508: if (Amat) {
509: MatSetNullSpace(Amat,nsp);
510: MatNullSpaceDestroy(&nsp);
511: } else SETERRQ(comm,PETSC_ERR_ARG_WRONGSTATE,"Cannot set nullspace, matrix has not yet been provided");
512: }
514: flg = PETSC_FALSE;
515: if (ksp->pc) {
516: PetscObjectTypeCompare((PetscObject)ksp->pc,PCKSP,&flg);
517: if (!flg) PetscObjectTypeCompare((PetscObject)ksp->pc,PCBJACOBI,&flg);
518: if (!flg) PetscObjectTypeCompare((PetscObject)ksp->pc,PCDEFLATION,&flg);
519: }
521: if (flg) {
522: /* A hack for using dynamic tolerance in preconditioner */
523: PetscOptionsString("-sub_ksp_dynamic_tolerance","Use dynamic tolerance for PC if PC is a KSP","KSPMonitorDynamicTolerance","stdout",monfilename,sizeof(monfilename),&flg);
524: if (flg) {
525: KSPDynTolCtx *scale;
526: PetscMalloc1(1,&scale);
527: scale->bnrm = -1.0;
528: scale->coef = 1.0;
529: PetscOptionsReal("-sub_ksp_dynamic_tolerance_param","Parameter of dynamic tolerance for inner PCKSP","KSPMonitorDynamicToleranceParam",scale->coef,&scale->coef,&flg);
530: KSPMonitorSet(ksp,KSPMonitorDynamicTolerance,scale,KSPMonitorDynamicToleranceDestroy);
531: }
532: }
534: /*
535: Calls Python function
536: */
537: PetscOptionsString("-ksp_monitor_python","Use Python function","KSPMonitorSet",NULL,monfilename,sizeof(monfilename),&flg);
538: if (flg) {PetscPythonMonitorSet((PetscObject)ksp,monfilename);}
539: /*
540: Graphically plots preconditioned residual norm and range of residual element values
541: */
542: PetscOptionsBool("-ksp_monitor_lg_range","Monitor graphically range of preconditioned residual norm","KSPMonitorSet",PETSC_FALSE,&flg,&set);
543: if (set && flg) {
544: PetscViewer ctx;
546: PetscViewerDrawOpen(comm,NULL,NULL,PETSC_DECIDE,PETSC_DECIDE,400,300,&ctx);
547: KSPMonitorSet(ksp,KSPMonitorLGRange,ctx,(PetscErrorCode (*)(void**))PetscViewerDestroy);
548: }
549: /* TODO Do these show up in help? */
550: PetscOptionsHasName(((PetscObject) ksp)->options, prefix, "-ksp_converged_rate", &flg);
551: if (flg) {
552: const char *RateTypes[] = {"default", "residual", "error", "PetscRateType", "RATE_", NULL};
553: PetscEnum rtype = (PetscEnum) 1;
555: PetscOptionsGetEnum(((PetscObject) ksp)->options, prefix, "-ksp_converged_rate_type", RateTypes, &rtype, &flg);
556: if (rtype == (PetscEnum) 0 || rtype == (PetscEnum) 1) {KSPSetResidualHistory(ksp, NULL, PETSC_DETERMINE, PETSC_TRUE);}
557: if (rtype == (PetscEnum) 0 || rtype == (PetscEnum) 2) {KSPSetErrorHistory(ksp, NULL, PETSC_DETERMINE, PETSC_TRUE);}
558: }
559: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view",&ksp->viewer,&ksp->format,&ksp->view);
560: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_pre",&ksp->viewerPre,&ksp->formatPre,&ksp->viewPre);
562: flg = PETSC_FALSE;
563: PetscOptionsBool("-ksp_converged_reason_view_cancel","Cancel all the converged reason view functions set using KSPConvergedReasonViewSet","KSPConvergedReasonViewCancel",PETSC_FALSE,&flg,&set);
564: if (set && flg) {
565: KSPConvergedReasonViewCancel(ksp);
566: }
567: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_converged_rate",&ksp->viewerRate,&ksp->formatRate,&ksp->viewRate);
568: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_mat",&ksp->viewerMat,&ksp->formatMat,&ksp->viewMat);
569: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_pmat",&ksp->viewerPMat,&ksp->formatPMat,&ksp->viewPMat);
570: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_rhs",&ksp->viewerRhs,&ksp->formatRhs,&ksp->viewRhs);
571: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_solution",&ksp->viewerSol,&ksp->formatSol,&ksp->viewSol);
572: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_mat_explicit",&ksp->viewerMatExp,&ksp->formatMatExp,&ksp->viewMatExp);
573: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_eigenvalues",&ksp->viewerEV,&ksp->formatEV,&ksp->viewEV);
574: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_singularvalues",&ksp->viewerSV,&ksp->formatSV,&ksp->viewSV);
575: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_eigenvalues_explicit",&ksp->viewerEVExp,&ksp->formatEVExp,&ksp->viewEVExp);
576: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_final_residual",&ksp->viewerFinalRes,&ksp->formatFinalRes,&ksp->viewFinalRes);
577: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_preconditioned_operator_explicit",&ksp->viewerPOpExp,&ksp->formatPOpExp,&ksp->viewPOpExp);
578: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_view_diagonal_scale",&ksp->viewerDScale,&ksp->formatDScale,&ksp->viewDScale);
580: /* Deprecated options */
581: if (!ksp->viewEV) {
582: PetscOptionsDeprecated("-ksp_compute_eigenvalues",NULL,"3.9","Use -ksp_view_eigenvalues");
583: PetscOptionsGetViewer(comm, ((PetscObject) ksp)->options,prefix, "-ksp_compute_eigenvalues",&ksp->viewerEV,&ksp->formatEV,&ksp->viewEV);
584: }
585: if (!ksp->viewEV) {
586: PetscOptionsDeprecated("-ksp_plot_eigenvalues",NULL,"3.9","Use -ksp_view_eigenvalues draw");
587: PetscOptionsName("-ksp_plot_eigenvalues", "[deprecated since PETSc 3.9; use -ksp_view_eigenvalues draw]", "KSPView", &ksp->viewEV);
588: if (ksp->viewEV) {
589: ksp->formatEV = PETSC_VIEWER_DEFAULT;
590: ksp->viewerEV = PETSC_VIEWER_DRAW_(comm);
591: PetscObjectReference((PetscObject) ksp->viewerEV);
592: }
593: }
594: if (!ksp->viewEV) {
595: PetscOptionsDeprecated("-ksp_plot_eigencontours",NULL,"3.9","Use -ksp_view_eigenvalues draw::draw_contour");
596: PetscOptionsName("-ksp_plot_eigencontours", "[deprecated since PETSc 3.9; use -ksp_view_eigenvalues draw::draw_contour]", "KSPView", &ksp->viewEV);
597: if (ksp->viewEV) {
598: ksp->formatEV = PETSC_VIEWER_DRAW_CONTOUR;
599: ksp->viewerEV = PETSC_VIEWER_DRAW_(comm);
600: PetscObjectReference((PetscObject) ksp->viewerEV);
601: }
602: }
603: if (!ksp->viewEVExp) {
604: PetscOptionsDeprecated("-ksp_compute_eigenvalues_explicitly",NULL,"3.9","Use -ksp_view_eigenvalues_explicit");
605: PetscOptionsGetViewer(comm, ((PetscObject) ksp)->options,prefix, "-ksp_compute_eigenvalues_explicitly",&ksp->viewerEVExp,&ksp->formatEVExp,&ksp->viewEVExp);
606: }
607: if (!ksp->viewEVExp) {
608: PetscOptionsDeprecated("-ksp_plot_eigenvalues_explicitly",NULL,"3.9","Use -ksp_view_eigenvalues_explicit draw");
609: PetscOptionsName("-ksp_plot_eigenvalues_explicitly","[deprecated since PETSc 3.9; use -ksp_view_eigenvalues_explicit draw]","KSPView",&ksp->viewEVExp);
610: if (ksp->viewEVExp) {
611: ksp->formatEVExp = PETSC_VIEWER_DEFAULT;
612: ksp->viewerEVExp = PETSC_VIEWER_DRAW_(comm);
613: PetscObjectReference((PetscObject) ksp->viewerEVExp);
614: }
615: }
616: if (!ksp->viewSV) {
617: PetscOptionsDeprecated("-ksp_compute_singularvalues",NULL,"3.9","Use -ksp_view_singularvalues");
618: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_compute_singularvalues",&ksp->viewerSV,&ksp->formatSV,&ksp->viewSV);
619: }
620: if (!ksp->viewFinalRes) {
621: PetscOptionsDeprecated("-ksp_final_residual",NULL,"3.9","Use -ksp_view_final_residual");
622: PetscOptionsGetViewer(comm,((PetscObject) ksp)->options,prefix,"-ksp_final_residual",&ksp->viewerFinalRes,&ksp->formatFinalRes,&ksp->viewFinalRes);
623: }
625: #if defined(PETSC_HAVE_SAWS)
626: /*
627: Publish convergence information using AMS
628: */
629: PetscOptionsBool("-ksp_monitor_saws","Publish KSP progress using SAWs","KSPMonitorSet",PETSC_FALSE,&flg,&set);
630: if (set && flg) {
631: void *ctx;
632: KSPMonitorSAWsCreate(ksp,&ctx);
633: KSPMonitorSet(ksp,KSPMonitorSAWs,ctx,KSPMonitorSAWsDestroy);
634: KSPSetComputeSingularValues(ksp,PETSC_TRUE);
635: }
636: #endif
638: /* -----------------------------------------------------------------------*/
639: KSPSetUpNorms_Private(ksp,PETSC_FALSE,NULL,&pcside);
640: PetscOptionsEnum("-ksp_pc_side","KSP preconditioner side","KSPSetPCSide",PCSides,(PetscEnum)pcside,(PetscEnum*)&pcside,&flg);
641: if (flg) {KSPSetPCSide(ksp,pcside);}
643: if (ksp->viewSV || ksp->viewEV) {
644: KSPSetComputeSingularValues(ksp,PETSC_TRUE);
645: }
647: #if defined(PETSC_HAVE_SAWS)
648: {
649: PetscBool set;
650: flg = PETSC_FALSE;
651: PetscOptionsBool("-ksp_saws_block","Block for SAWs at end of KSPSolve","PetscObjectSAWsBlock",((PetscObject)ksp)->amspublishblock,&flg,&set);
652: if (set) {
653: PetscObjectSAWsSetBlock((PetscObject)ksp,flg);
654: }
655: }
656: #endif
658: nmax = ksp->nmax;
659: PetscOptionsDeprecated("-ksp_matsolve_block_size","-ksp_matsolve_batch_size","3.15",NULL);
660: PetscOptionsInt("-ksp_matsolve_batch_size", "Maximum number of columns treated simultaneously", "KSPSetMatSolveBatchSize", nmax, &nmax, &flg);
661: if (flg) {
662: KSPSetMatSolveBatchSize(ksp, nmax);
663: }
665: flg = PETSC_FALSE;
666: PetscOptionsBool("-ksp_use_explicittranspose","Explicitly tranpose the system in KSPSolveTranspose","KSPSetUseExplicitTranspose",ksp->transpose.use_explicittranspose,&flg,&set);
667: if (set) {
668: KSPSetUseExplicitTranspose(ksp,flg);
669: }
671: if (ksp->ops->setfromoptions) {
672: (*ksp->ops->setfromoptions)(PetscOptionsObject,ksp);
673: }
674: skipoptions:
675: /* process any options handlers added with PetscObjectAddOptionsHandler() */
676: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)ksp);
677: PetscOptionsEnd();
678: ksp->setfromoptionscalled++;
679: return(0);
680: }
682: /*@
683: KSPResetFromOptions - Sets various KSP parameters from user options ONLY if the KSP was previously set from options
685: Collective on ksp
687: Input Parameter:
688: . ksp - the KSP context
690: Level: beginner
692: .seealso: KSPSetFromOptions(), KSPSetOptionsPrefix()
693: @*/
694: PetscErrorCode KSPResetFromOptions(KSP ksp)
695: {
699: if (ksp->setfromoptionscalled) {KSPSetFromOptions(ksp);}
700: return(0);
701: }