Actual source code: itcl.c

  1: /*
  2:     Code for setting KSP options from the options database.
  3: */

  5: #include <petsc/private/kspimpl.h>
  6: #include <petscdraw.h>

  8: /*@C
  9:   KSPSetOptionsPrefix - Sets the prefix used for searching for all
 10:   `KSP` options in the database.

 12:   Logically Collective

 14:   Input Parameters:
 15: + ksp    - the Krylov context
 16: - prefix - the prefix string to prepend to all `KSP` option requests

 18:   Level: advanced

 20:   Notes:
 21:   A hyphen (-) must NOT be given at the beginning of the prefix name.
 22:   The first character of all runtime options is AUTOMATICALLY the
 23:   hyphen.

 25:   For example, to distinguish between the runtime options for two
 26:   different `KSP` contexts, one could call
 27: .vb
 28:       KSPSetOptionsPrefix(ksp1,"sys1_")
 29:       KSPSetOptionsPrefix(ksp2,"sys2_")
 30: .ve

 32:   This would enable use of different options for each system, such as
 33: .vb
 34:       -sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3
 35:       -sys2_ksp_type bcgs  -sys2_ksp_rtol 1.e-4
 36: .ve

 38: .seealso: [](ch_ksp), `KSP`, `KSPAppendOptionsPrefix()`, `KSPGetOptionsPrefix()`, `KSPSetFromOptions()`
 39: @*/
 40: PetscErrorCode KSPSetOptionsPrefix(KSP ksp, const char prefix[])
 41: {
 42:   PetscBool ispcmpi;

 44:   PetscFunctionBegin;
 46:   if (!ksp->pc) PetscCall(KSPGetPC(ksp, &ksp->pc));
 47:   PetscCall(PetscObjectTypeCompare((PetscObject)ksp->pc, PCMPI, &ispcmpi));
 48:   if (ispcmpi) {
 49:     size_t     len;
 50:     const char suffix[] = "mpi_linear_solver_server_";
 51:     char      *newprefix;

 53:     PetscCall(PetscStrlen(prefix, &len));
 54:     PetscCall(PetscMalloc1(len + sizeof(suffix) + 1, &newprefix));
 55:     PetscCall(PetscStrncpy(newprefix, prefix, len + sizeof(suffix)));
 56:     PetscCall(PetscStrlcat(newprefix, suffix, len + sizeof(suffix)));
 57:     PetscCall(PCSetOptionsPrefix(ksp->pc, newprefix));
 58:     PetscCall(PetscObjectSetOptionsPrefix((PetscObject)ksp, newprefix));
 59:     PetscCall(PetscFree(newprefix));
 60:   } else {
 61:     PetscCall(PCSetOptionsPrefix(ksp->pc, prefix));
 62:     PetscCall(PetscObjectSetOptionsPrefix((PetscObject)ksp, prefix));
 63:   }
 64:   PetscFunctionReturn(PETSC_SUCCESS);
 65: }

 67: /*@C
 68:   KSPAppendOptionsPrefix - Appends to the prefix used for searching for all
 69:   `KSP` options in the database.

 71:   Logically Collective

 73:   Input Parameters:
 74: + ksp    - the Krylov context
 75: - prefix - the prefix string to prepend to all `KSP` option requests

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

 81:   Level: advanced

 83: .seealso: [](ch_ksp), `KSP`, `KSPSetOptionsPrefix()`, `KSPGetOptionsPrefix()`, `KSPSetFromOptions()`
 84: @*/
 85: PetscErrorCode KSPAppendOptionsPrefix(KSP ksp, const char prefix[])
 86: {
 87:   PetscFunctionBegin;
 89:   if (!ksp->pc) PetscCall(KSPGetPC(ksp, &ksp->pc));
 90:   PetscCall(PCAppendOptionsPrefix(ksp->pc, prefix));
 91:   PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)ksp, prefix));
 92:   PetscFunctionReturn(PETSC_SUCCESS);
 93: }

 95: /*@
 96:   KSPSetUseFischerGuess - Use the Paul Fischer algorithm or its variants to compute initial guesses for a set of solves with related right hand sides

 98:   Logically Collective

100:   Input Parameters:
101: + ksp   - the Krylov context
102: . model - use model 1, model 2, model 3, or any other number to turn it off
103: - size  - size of subspace used to generate initial guess

105:   Options Database Key:
106: . -ksp_fischer_guess <model,size> - uses the Fischer initial guess generator for repeated linear solves

108:   Level: advanced

110: .seealso: [](ch_ksp), `KSP`, `KSPSetOptionsPrefix()`, `KSPAppendOptionsPrefix()`, `KSPSetGuess()`, `KSPGetGuess()`, `KSPGuess`
111: @*/
112: PetscErrorCode KSPSetUseFischerGuess(KSP ksp, PetscInt model, PetscInt size)
113: {
114:   KSPGuess guess;

116:   PetscFunctionBegin;
120:   PetscCall(KSPGetGuess(ksp, &guess));
121:   PetscCall(KSPGuessSetType(guess, KSPGUESSFISCHER));
122:   PetscCall(KSPGuessFischerSetModel(guess, model, size));
123:   PetscFunctionReturn(PETSC_SUCCESS);
124: }

126: /*@
127:   KSPSetGuess - Set the initial guess object

129:   Logically Collective

131:   Input Parameters:
132: + ksp   - the Krylov context
133: - guess - the object created with `KSPGuessCreate()`

135:   Level: advanced

137:   Notes:
138:   this allows a single `KSP` to be used with several different initial guess generators (likely for different linear
139:   solvers, see `KSPSetPC()`).

141:   This increases the reference count of the guess object, you must destroy the object with `KSPGuessDestroy()`
142:   before the end of the program.

144: .seealso: [](ch_ksp), `KSP`, `KSPGuess`, `KSPSetOptionsPrefix()`, `KSPAppendOptionsPrefix()`, `KSPSetUseFischerGuess()`, `KSPGetGuess()`
145: @*/
146: PetscErrorCode KSPSetGuess(KSP ksp, KSPGuess guess)
147: {
148:   PetscFunctionBegin;
151:   PetscCall(PetscObjectReference((PetscObject)guess));
152:   PetscCall(KSPGuessDestroy(&ksp->guess));
153:   ksp->guess      = guess;
154:   ksp->guess->ksp = ksp;
155:   PetscFunctionReturn(PETSC_SUCCESS);
156: }

158: /*@
159:   KSPGetGuess - Gets the initial guess generator for the `KSP`.

161:   Not Collective

163:   Input Parameter:
164: . ksp - the Krylov context

166:   Output Parameter:
167: . guess - the object

169:   Level: developer

171: .seealso: [](ch_ksp), `KSPGuess`, `KSP`, `KSPSetOptionsPrefix()`, `KSPAppendOptionsPrefix()`, `KSPSetUseFischerGuess()`, `KSPSetGuess()`
172: @*/
173: PetscErrorCode KSPGetGuess(KSP ksp, KSPGuess *guess)
174: {
175:   PetscFunctionBegin;
177:   PetscAssertPointer(guess, 2);
178:   if (!ksp->guess) {
179:     const char *prefix;

181:     PetscCall(KSPGuessCreate(PetscObjectComm((PetscObject)ksp), &ksp->guess));
182:     PetscCall(PetscObjectGetOptionsPrefix((PetscObject)ksp, &prefix));
183:     if (prefix) PetscCall(PetscObjectSetOptionsPrefix((PetscObject)ksp->guess, prefix));
184:     ksp->guess->ksp = ksp;
185:   }
186:   *guess = ksp->guess;
187:   PetscFunctionReturn(PETSC_SUCCESS);
188: }

190: /*@C
191:   KSPGetOptionsPrefix - Gets the prefix used for searching for all
192:   `KSP` options in the database.

194:   Not Collective

196:   Input Parameter:
197: . ksp - the Krylov context

199:   Output Parameter:
200: . prefix - pointer to the prefix string used is returned

202:   Notes:
203:   On the fortran side, the user should pass in a string 'prefix' of
204:   sufficient length to hold the prefix.

206:   Level: advanced

208: .seealso: [](ch_ksp), `KSP`, `KSPSetFromOptions()`, `KSPSetOptionsPrefix()`, `KSPAppendOptionsPrefix()`
209: @*/
210: PetscErrorCode KSPGetOptionsPrefix(KSP ksp, const char *prefix[])
211: {
212:   PetscFunctionBegin;
214:   PetscCall(PetscObjectGetOptionsPrefix((PetscObject)ksp, prefix));
215:   PetscFunctionReturn(PETSC_SUCCESS);
216: }

218: static PetscErrorCode PetscViewerAndFormatCreate_Internal(PetscViewer viewer, PetscViewerFormat format, void *ctx, PetscViewerAndFormat **vf)
219: {
220:   PetscFunctionBegin;
221:   PetscCall(PetscViewerAndFormatCreate(viewer, format, vf));
222:   (*vf)->data = ctx;
223:   PetscFunctionReturn(PETSC_SUCCESS);
224: }

226: /*@C
227:   KSPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type indicated by the user in the options database

229:   Collective

231:   Input Parameters:
232: + ksp  - `KSP` object you wish to monitor
233: . opt  - the command line option for this monitor
234: . name - the monitor type one is seeking
235: - ctx  - An optional user context for the monitor, or NULL

237:   Level: developer

239: .seealso: [](ch_ksp), `KSPMonitorRegister()`, `KSPMonitorSet()`, `PetscOptionsGetViewer()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`,
240:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
241:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
242:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
243:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
244:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
245:           `PetscOptionsFList()`, `PetscOptionsEList()`
246: @*/
247: PetscErrorCode KSPMonitorSetFromOptions(KSP ksp, const char opt[], const char name[], void *ctx)
248: {
249:   PetscErrorCode (*mfunc)(KSP, PetscInt, PetscReal, void *);
250:   PetscErrorCode (*cfunc)(PetscViewer, PetscViewerFormat, void *, PetscViewerAndFormat **);
251:   PetscErrorCode (*dfunc)(PetscViewerAndFormat **);
252:   PetscViewerAndFormat *vf;
253:   PetscViewer           viewer;
254:   PetscViewerFormat     format;
255:   PetscViewerType       vtype;
256:   char                  key[PETSC_MAX_PATH_LEN];
257:   PetscBool             all, flg;
258:   const char           *prefix = NULL;

260:   PetscFunctionBegin;
261:   PetscCall(PetscStrcmp(opt, "-all_ksp_monitor", &all));
262:   if (!all) PetscCall(PetscObjectGetOptionsPrefix((PetscObject)ksp, &prefix));
263:   PetscCall(PetscOptionsGetViewer(PetscObjectComm((PetscObject)ksp), ((PetscObject)ksp)->options, prefix, opt, &viewer, &format, &flg));
264:   if (!flg) PetscFunctionReturn(PETSC_SUCCESS);

266:   PetscCall(PetscViewerGetType(viewer, &vtype));
267:   PetscCall(KSPMonitorMakeKey_Internal(name, vtype, format, key));
268:   PetscCall(PetscFunctionListFind(KSPMonitorList, key, &mfunc));
269:   PetscCall(PetscFunctionListFind(KSPMonitorCreateList, key, &cfunc));
270:   PetscCall(PetscFunctionListFind(KSPMonitorDestroyList, key, &dfunc));
271:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
272:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

274:   PetscCall((*cfunc)(viewer, format, ctx, &vf));
275:   PetscCall(PetscObjectDereference((PetscObject)viewer));
276:   PetscCall(KSPMonitorSet(ksp, mfunc, vf, (PetscErrorCode(*)(void **))dfunc));
277:   PetscFunctionReturn(PETSC_SUCCESS);
278: }

280: PETSC_INTERN PetscErrorCode KSPCheckPCMPI(KSP);

282: /*@
283:   KSPSetFromOptions - Sets `KSP` options from the options database.
284:   This routine must be called before `KSPSetUp()` if the user is to be
285:   allowed to set the Krylov type.

287:   Collective

289:   Input Parameter:
290: . ksp - the Krylov space context

292:   Options Database Keys:
293: + -ksp_max_it                                                             - maximum number of linear iterations
294: . -ksp_min_it                                                             - miminum number of linear iterations to use, defaults to zero
295: . -ksp_rtol rtol                                                          - relative tolerance used in default determination of convergence, i.e.
296:                 if residual norm decreases by this factor than convergence is declared
297: . -ksp_atol abstol                                                        - absolute tolerance used in default convergence test, i.e. if residual
298:                 norm is less than this then convergence is declared
299: . -ksp_divtol tol                                                         - if residual norm increases by this factor than divergence is declared
300: . -ksp_converged_use_initial_residual_norm                                - see `KSPConvergedDefaultSetUIRNorm()`
301: . -ksp_converged_use_min_initial_residual_norm                            - see `KSPConvergedDefaultSetUMIRNorm()`
302: . -ksp_converged_maxits                                                   - see `KSPConvergedDefaultSetConvergedMaxits()`
303: . -ksp_norm_type                                                          - none - skip norms used in convergence tests (useful only when not using
304:                        convergence test (say you always want to run with 5 iterations) to
305:                        save on communication overhead
306:                     preconditioned - default for left preconditioning
307:                     unpreconditioned - see `KSPSetNormType()`
308:                     natural - see `KSPSetNormType()`
309: . -ksp_check_norm_iteration it                                            - do not compute residual norm until iteration number it (does compute at 0th iteration)
310:        works only for `KSPBCGS`, `KSPIBCGS` and and `KSPCG`
311: . -ksp_lag_norm                                                           - compute the norm of the residual for the ith iteration on the i+1 iteration; this means that one can use
312:        the norm of the residual for convergence test WITHOUT an extra `MPI_Allreduce()` limiting global synchronizations.
313:        This will require 1 more iteration of the solver than usual.
314: . -ksp_guess_type                                                         - Type of initial guess generator for repeated linear solves
315: . -ksp_fischer_guess <model,size>                                         - uses the Fischer initial guess generator for repeated linear solves
316: . -ksp_constant_null_space                                                - assume the operator (matrix) has the constant vector in its null space
317: . -ksp_test_null_space                                                    - tests the null space set with `MatSetNullSpace()` to see if it truly is a null space
318: . -ksp_knoll                                                              - compute initial guess by applying the preconditioner to the right hand side
319: . -ksp_monitor_cancel                                                     - cancel all previous convergene monitor routines set
320: . -ksp_monitor                                                            - print residual norm at each iteration
321: . -ksp_monitor draw::draw_lg                                              - plot residual norm at each iteration
322: . -ksp_monitor_true_residual                                              - print true residual norm at each iteration
323: . -all_ksp_monitor <optional filename>                                    - print residual norm at each iteration for ALL KSP solves, regardless of their prefix. This is
324:                                            useful for `PCFIELDSPLIT`, `PCMG`, etc that have inner solvers and you wish to track the convergence of all the solvers
325: . -ksp_monitor_solution [ascii binary or draw][:filename][:format option] - plot solution at each iteration
326: . -ksp_monitor_singular_value                                             - monitor extreme singular values at each iteration
327: . -ksp_converged_reason                                                   - view the convergence state at the end of the solve
328: . -ksp_use_explicittranspose                                              - transpose the system explicitly in KSPSolveTranspose
329: . -ksp_error_if_not_converged                                             - stop the program as soon as an error is detected in a `KSPSolve()`, `KSP_DIVERGED_ITS` is not treated as an error on inner solves
330: - -ksp_converged_rate                                                     - view the convergence rate at the end of the solve

332:   Notes:
333:   To see all options, run your program with the -help option
334:   or consult [](ch_ksp)

336:   Level: beginner

338: .seealso: [](ch_ksp), `KSP`, `KSPSetOptionsPrefix()`, `KSPResetFromOptions()`, `KSPSetUseFischerGuess()`
339: @*/
340: PetscErrorCode KSPSetFromOptions(KSP ksp)
341: {
342:   const char *convtests[] = {"default", "skip", "lsqr"}, *prefix;
343:   char        type[256], guesstype[256], monfilename[PETSC_MAX_PATH_LEN];
344:   PetscBool   flg, flag, reuse, set;
345:   PetscInt    indx, model[2] = {0, 0}, nmax;
346:   KSPNormType normtype;
347:   PCSide      pcside;
348:   void       *ctx;
349:   MPI_Comm    comm;

351:   PetscFunctionBegin;
353:   PetscCall(KSPCheckPCMPI(ksp));

355:   PetscCall(PetscObjectGetComm((PetscObject)ksp, &comm));
356:   PetscCall(PetscObjectGetOptionsPrefix((PetscObject)ksp, &prefix));
357:   if (!ksp->skippcsetfromoptions) {
358:     if (!ksp->pc) PetscCall(KSPGetPC(ksp, &ksp->pc));
359:     PetscCall(PCSetFromOptions(ksp->pc));
360:   }

362:   PetscCall(KSPRegisterAll());
363:   PetscObjectOptionsBegin((PetscObject)ksp);
364:   PetscCall(PetscOptionsFList("-ksp_type", "Krylov method", "KSPSetType", KSPList, (char *)(((PetscObject)ksp)->type_name ? ((PetscObject)ksp)->type_name : KSPGMRES), type, 256, &flg));
365:   if (flg) PetscCall(KSPSetType(ksp, type));
366:   /*
367:     Set the type if it was never set.
368:   */
369:   if (!((PetscObject)ksp)->type_name) PetscCall(KSPSetType(ksp, KSPGMRES));

371:   PetscCall(KSPResetViewers(ksp));

373:   /* Cancels all monitors hardwired into code before call to KSPSetFromOptions() */
374:   PetscCall(PetscOptionsBool("-ksp_monitor_cancel", "Remove any hardwired monitor routines", "KSPMonitorCancel", PETSC_FALSE, &flg, &set));
375:   if (set && flg) PetscCall(KSPMonitorCancel(ksp));
376:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor", "preconditioned_residual", NULL));
377:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_short", "preconditioned_residual_short", NULL));
378:   PetscCall(KSPMonitorSetFromOptions(ksp, "-all_ksp_monitor", "preconditioned_residual", NULL));
379:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_range", "preconditioned_residual_range", NULL));
380:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_true_residual", "true_residual", NULL));
381:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_max", "true_residual_max", NULL));
382:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_solution", "solution", NULL));
383:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_singular_value", "singular_value", ksp));
384:   PetscCall(KSPMonitorSetFromOptions(ksp, "-ksp_monitor_error", "error", ksp));
385:   PetscCall(PetscOptionsBool("-ksp_monitor_pause_final", "Pauses all draw monitors at the final iterate", "KSPMonitorPauseFinal_Internal", PETSC_FALSE, &ksp->pauseFinal, NULL));
386:   PetscCall(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));
387:   if (flg) PetscCall(KSPSetInitialGuessNonzero(ksp, flag));

389:   PetscCall(PetscObjectTypeCompare((PetscObject)ksp, KSPPREONLY, &flg));
390:   if (flg) {
391:     PetscCall(KSPGetReusePreconditioner(ksp, &reuse));
392:     PetscCall(PetscOptionsBool("-ksp_reuse_preconditioner", "Use initial preconditioner and don't ever compute a new one", "KSPReusePreconditioner", reuse, &reuse, NULL));
393:     PetscCall(KSPSetReusePreconditioner(ksp, reuse));
394:     PetscCall(PetscOptionsBool("-ksp_error_if_not_converged", "Generate error if solver does not converge", "KSPSetErrorIfNotConverged", ksp->errorifnotconverged, &ksp->errorifnotconverged, NULL));
395:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view", &ksp->viewer, &ksp->format, &ksp->view));
396:     flg = PETSC_FALSE;
397:     PetscCall(PetscOptionsBool("-ksp_converged_reason_view_cancel", "Cancel all the converged reason view functions set using KSPConvergedReasonViewSet", "KSPConvergedReasonViewCancel", PETSC_FALSE, &flg, &set));
398:     if (set && flg) PetscCall(KSPConvergedReasonViewCancel(ksp));
399:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_mat", &ksp->viewerMat, &ksp->formatMat, &ksp->viewMat));
400:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_pmat", &ksp->viewerPMat, &ksp->formatPMat, &ksp->viewPMat));
401:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_rhs", &ksp->viewerRhs, &ksp->formatRhs, &ksp->viewRhs));
402:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_solution", &ksp->viewerSol, &ksp->formatSol, &ksp->viewSol));
403:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_mat_explicit", &ksp->viewerMatExp, &ksp->formatMatExp, &ksp->viewMatExp));
404:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_final_residual", &ksp->viewerFinalRes, &ksp->formatFinalRes, &ksp->viewFinalRes));
405:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_preconditioned_operator_explicit", &ksp->viewerPOpExp, &ksp->formatPOpExp, &ksp->viewPOpExp));
406:     PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_diagonal_scale", &ksp->viewerDScale, &ksp->formatDScale, &ksp->viewDScale));

408:     PetscCall(KSPGetDiagonalScale(ksp, &flag));
409:     PetscCall(PetscOptionsBool("-ksp_diagonal_scale", "Diagonal scale matrix before building preconditioner", "KSPSetDiagonalScale", flag, &flag, &flg));
410:     if (flg) PetscCall(KSPSetDiagonalScale(ksp, flag));
411:     PetscCall(KSPGetDiagonalScaleFix(ksp, &flag));
412:     PetscCall(PetscOptionsBool("-ksp_diagonal_scale_fix", "Fix diagonally scaled matrix after solve", "KSPSetDiagonalScaleFix", flag, &flag, &flg));
413:     if (flg) PetscCall(KSPSetDiagonalScaleFix(ksp, flag));
414:     nmax = ksp->nmax;
415:     PetscCall(PetscOptionsDeprecated("-ksp_matsolve_block_size", "-ksp_matsolve_batch_size", "3.15", NULL));
416:     PetscCall(PetscOptionsInt("-ksp_matsolve_batch_size", "Maximum number of columns treated simultaneously", "KSPSetMatSolveBatchSize", nmax, &nmax, &flg));
417:     if (flg) PetscCall(KSPSetMatSolveBatchSize(ksp, nmax));
418:     goto skipoptions;
419:   }

421:   PetscCall(PetscOptionsBoundedInt("-ksp_max_it", "Maximum number of iterations", "KSPSetTolerances", ksp->max_it, &ksp->max_it, NULL, 0));
422:   PetscCall(PetscOptionsRangeInt("-ksp_min_it", "Minimum number of iterations", "KSPSetMinimumIterations", ksp->min_it, &ksp->min_it, NULL, 0, ksp->max_it));
423:   PetscCall(PetscOptionsReal("-ksp_rtol", "Relative decrease in residual norm", "KSPSetTolerances", ksp->rtol, &ksp->rtol, NULL));
424:   PetscCall(PetscOptionsReal("-ksp_atol", "Absolute value of residual norm", "KSPSetTolerances", ksp->abstol, &ksp->abstol, NULL));
425:   PetscCall(PetscOptionsReal("-ksp_divtol", "Residual norm increase cause divergence", "KSPSetTolerances", ksp->divtol, &ksp->divtol, NULL));

427:   PetscCall(PetscOptionsBool("-ksp_converged_use_initial_residual_norm", "Use initial residual norm for computing relative convergence", "KSPConvergedDefaultSetUIRNorm", PETSC_FALSE, &flag, &set));
428:   if (set && flag) PetscCall(KSPConvergedDefaultSetUIRNorm(ksp));
429:   PetscCall(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));
430:   if (set && flag) PetscCall(KSPConvergedDefaultSetUMIRNorm(ksp));
431:   PetscCall(PetscOptionsBool("-ksp_converged_maxits", "Declare convergence if the maximum number of iterations is reached", "KSPConvergedDefaultSetConvergedMaxits", PETSC_FALSE, &flag, &set));
432:   if (set) PetscCall(KSPConvergedDefaultSetConvergedMaxits(ksp, flag));
433:   PetscCall(KSPGetConvergedNegativeCurvature(ksp, &flag));
434:   PetscCall(PetscOptionsBool("-ksp_converged_neg_curve", "Declare convergence if negative curvature is detected", "KSPConvergedNegativeCurvature", flag, &flag, &set));
435:   if (set) PetscCall(KSPSetConvergedNegativeCurvature(ksp, flag));
436:   PetscCall(KSPGetReusePreconditioner(ksp, &reuse));
437:   PetscCall(PetscOptionsBool("-ksp_reuse_preconditioner", "Use initial preconditioner and don't ever compute a new one", "KSPReusePreconditioner", reuse, &reuse, NULL));
438:   PetscCall(KSPSetReusePreconditioner(ksp, reuse));

440:   PetscCall(PetscOptionsBool("-ksp_knoll", "Use preconditioner applied to b for initial guess", "KSPSetInitialGuessKnoll", ksp->guess_knoll, &ksp->guess_knoll, NULL));
441:   PetscCall(PetscOptionsBool("-ksp_error_if_not_converged", "Generate error if solver does not converge", "KSPSetErrorIfNotConverged", ksp->errorifnotconverged, &ksp->errorifnotconverged, NULL));
442:   PetscCall(PetscOptionsFList("-ksp_guess_type", "Initial guess in Krylov method", NULL, KSPGuessList, NULL, guesstype, 256, &flg));
443:   if (flg) {
444:     PetscCall(KSPGetGuess(ksp, &ksp->guess));
445:     PetscCall(KSPGuessSetType(ksp->guess, guesstype));
446:     PetscCall(KSPGuessSetFromOptions(ksp->guess));
447:   } else { /* old option for KSP */
448:     nmax = 2;
449:     PetscCall(PetscOptionsIntArray("-ksp_fischer_guess", "Use Paul Fischer's algorithm or its variants for initial guess", "KSPSetUseFischerGuess", model, &nmax, &flag));
450:     if (flag) {
451:       PetscCheck(nmax == 2, comm, PETSC_ERR_ARG_OUTOFRANGE, "Must pass in model,size as arguments");
452:       PetscCall(KSPSetUseFischerGuess(ksp, model[0], model[1]));
453:     }
454:   }

456:   PetscCall(PetscOptionsEList("-ksp_convergence_test", "Convergence test", "KSPSetConvergenceTest", convtests, 3, "default", &indx, &flg));
457:   if (flg) {
458:     switch (indx) {
459:     case 0:
460:       PetscCall(KSPConvergedDefaultCreate(&ctx));
461:       PetscCall(KSPSetConvergenceTest(ksp, KSPConvergedDefault, ctx, KSPConvergedDefaultDestroy));
462:       break;
463:     case 1:
464:       PetscCall(KSPSetConvergenceTest(ksp, KSPConvergedSkip, NULL, NULL));
465:       break;
466:     case 2:
467:       PetscCall(KSPConvergedDefaultCreate(&ctx));
468:       PetscCall(KSPSetConvergenceTest(ksp, KSPLSQRConvergedDefault, ctx, KSPConvergedDefaultDestroy));
469:       break;
470:     }
471:   }

473:   PetscCall(KSPSetUpNorms_Private(ksp, PETSC_FALSE, &normtype, NULL));
474:   PetscCall(PetscOptionsEnum("-ksp_norm_type", "KSP Norm type", "KSPSetNormType", KSPNormTypes, (PetscEnum)normtype, (PetscEnum *)&normtype, &flg));
475:   if (flg) PetscCall(KSPSetNormType(ksp, normtype));

477:   PetscCall(PetscOptionsInt("-ksp_check_norm_iteration", "First iteration to compute residual norm", "KSPSetCheckNormIteration", ksp->chknorm, &ksp->chknorm, NULL));

479:   PetscCall(PetscOptionsBool("-ksp_lag_norm", "Lag the calculation of the residual norm", "KSPSetLagNorm", ksp->lagnorm, &flag, &flg));
480:   if (flg) PetscCall(KSPSetLagNorm(ksp, flag));

482:   PetscCall(KSPGetDiagonalScale(ksp, &flag));
483:   PetscCall(PetscOptionsBool("-ksp_diagonal_scale", "Diagonal scale matrix before building preconditioner", "KSPSetDiagonalScale", flag, &flag, &flg));
484:   if (flg) PetscCall(KSPSetDiagonalScale(ksp, flag));
485:   PetscCall(KSPGetDiagonalScaleFix(ksp, &flag));
486:   PetscCall(PetscOptionsBool("-ksp_diagonal_scale_fix", "Fix diagonally scaled matrix after solve", "KSPSetDiagonalScaleFix", flag, &flag, &flg));
487:   if (flg) PetscCall(KSPSetDiagonalScaleFix(ksp, flag));

489:   PetscCall(PetscOptionsBool("-ksp_constant_null_space", "Add constant null space to Krylov solver matrix", "MatSetNullSpace", PETSC_FALSE, &flg, &set));
490:   if (set && flg) {
491:     MatNullSpace nsp;
492:     Mat          Amat = NULL;

494:     PetscCall(MatNullSpaceCreate(comm, PETSC_TRUE, 0, NULL, &nsp));
495:     if (ksp->pc) PetscCall(PCGetOperators(ksp->pc, &Amat, NULL));
496:     PetscCheck(Amat, comm, PETSC_ERR_ARG_WRONGSTATE, "Cannot set nullspace, matrix has not yet been provided");
497:     PetscCall(MatSetNullSpace(Amat, nsp));
498:     PetscCall(MatNullSpaceDestroy(&nsp));
499:   }

501:   flg = PETSC_FALSE;
502:   if (ksp->pc) {
503:     PetscCall(PetscObjectTypeCompare((PetscObject)ksp->pc, PCKSP, &flg));
504:     if (!flg) PetscCall(PetscObjectTypeCompare((PetscObject)ksp->pc, PCBJACOBI, &flg));
505:     if (!flg) PetscCall(PetscObjectTypeCompare((PetscObject)ksp->pc, PCDEFLATION, &flg));
506:   }

508:   if (flg) {
509:     /* Using dynamic tolerance in preconditioner */
510:     PetscCall(PetscOptionsString("-sub_ksp_dynamic_tolerance", "Use dynamic tolerance for inner PC", "KSPMonitorDynamicTolerance", "stdout", monfilename, sizeof(monfilename), &flg));
511:     if (flg) {
512:       void     *scale;
513:       PetscReal coeff = 1.0;

515:       PetscCall(KSPMonitorDynamicToleranceCreate(&scale));
516:       PetscCall(PetscOptionsReal("-sub_ksp_dynamic_tolerance", "Coefficient of dynamic tolerance for inner PC", "KSPMonitorDynamicTolerance", coeff, &coeff, &flg));
517:       if (flg) PetscCall(KSPMonitorDynamicToleranceSetCoefficient(scale, coeff));
518:       PetscCall(KSPMonitorSet(ksp, KSPMonitorDynamicTolerance, scale, KSPMonitorDynamicToleranceDestroy));
519:     }
520:   }

522:   /*
523:    Calls Python function
524:   */
525:   PetscCall(PetscOptionsString("-ksp_monitor_python", "Use Python function", "KSPMonitorSet", NULL, monfilename, sizeof(monfilename), &flg));
526:   if (flg) PetscCall(PetscPythonMonitorSet((PetscObject)ksp, monfilename));
527:   /*
528:     Graphically plots preconditioned residual norm and range of residual element values
529:   */
530:   PetscCall(PetscOptionsBool("-ksp_monitor_lg_range", "Monitor graphically range of preconditioned residual norm", "KSPMonitorSet", PETSC_FALSE, &flg, &set));
531:   if (set && flg) {
532:     PetscViewer ctx;

534:     PetscCall(PetscViewerDrawOpen(comm, NULL, NULL, PETSC_DECIDE, PETSC_DECIDE, 400, 300, &ctx));
535:     PetscCall(KSPMonitorSet(ksp, KSPMonitorLGRange, ctx, (PetscErrorCode(*)(void **))PetscViewerDestroy));
536:   }
537:   /* TODO Do these show up in help? */
538:   PetscCall(PetscOptionsHasName(((PetscObject)ksp)->options, prefix, "-ksp_converged_rate", &flg));
539:   if (flg) {
540:     const char *RateTypes[] = {"default", "residual", "error", "PetscRateType", "RATE_", NULL};
541:     PetscEnum   rtype       = (PetscEnum)1;

543:     PetscCall(PetscOptionsGetEnum(((PetscObject)ksp)->options, prefix, "-ksp_converged_rate_type", RateTypes, &rtype, &flg));
544:     if (rtype == (PetscEnum)0 || rtype == (PetscEnum)1) PetscCall(KSPSetResidualHistory(ksp, NULL, PETSC_DETERMINE, PETSC_TRUE));
545:     if (rtype == (PetscEnum)0 || rtype == (PetscEnum)2) PetscCall(KSPSetErrorHistory(ksp, NULL, PETSC_DETERMINE, PETSC_TRUE));
546:   }
547:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view", &ksp->viewer, &ksp->format, &ksp->view));
548:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_pre", &ksp->viewerPre, &ksp->formatPre, &ksp->viewPre));

550:   flg = PETSC_FALSE;
551:   PetscCall(PetscOptionsBool("-ksp_converged_reason_view_cancel", "Cancel all the converged reason view functions set using KSPConvergedReasonViewSet", "KSPConvergedReasonViewCancel", PETSC_FALSE, &flg, &set));
552:   if (set && flg) PetscCall(KSPConvergedReasonViewCancel(ksp));
553:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_converged_rate", &ksp->viewerRate, &ksp->formatRate, &ksp->viewRate));
554:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_mat", &ksp->viewerMat, &ksp->formatMat, &ksp->viewMat));
555:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_pmat", &ksp->viewerPMat, &ksp->formatPMat, &ksp->viewPMat));
556:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_rhs", &ksp->viewerRhs, &ksp->formatRhs, &ksp->viewRhs));
557:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_solution", &ksp->viewerSol, &ksp->formatSol, &ksp->viewSol));
558:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_mat_explicit", &ksp->viewerMatExp, &ksp->formatMatExp, &ksp->viewMatExp));
559:   PetscCall(PetscOptionsDeprecated("-ksp_compute_eigenvalues", "-ksp_view_eigenvalues", "3.9", NULL));
560:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_eigenvalues", &ksp->viewerEV, &ksp->formatEV, &ksp->viewEV));
561:   PetscCall(PetscOptionsDeprecated("-ksp_compute_singularvalues", "-ksp_view_singularvalues", "3.9", NULL));
562:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_singularvalues", &ksp->viewerSV, &ksp->formatSV, &ksp->viewSV));
563:   PetscCall(PetscOptionsDeprecated("-ksp_compute_eigenvalues_explicitly", "-ksp_view_eigenvalues_explicit", "3.9", NULL));
564:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_eigenvalues_explicit", &ksp->viewerEVExp, &ksp->formatEVExp, &ksp->viewEVExp));
565:   PetscCall(PetscOptionsDeprecated("-ksp_final_residual", "-ksp_view_final_residual", "3.9", NULL));
566:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_final_residual", &ksp->viewerFinalRes, &ksp->formatFinalRes, &ksp->viewFinalRes));
567:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_preconditioned_operator_explicit", &ksp->viewerPOpExp, &ksp->formatPOpExp, &ksp->viewPOpExp));
568:   PetscCall(PetscOptionsGetViewer(comm, ((PetscObject)ksp)->options, prefix, "-ksp_view_diagonal_scale", &ksp->viewerDScale, &ksp->formatDScale, &ksp->viewDScale));

570:   /* Deprecated options */
571:   if (!ksp->viewEV) {
572:     /* Cannot remove the what otherwise would be redundant call to PetscOptionsName("-ksp_plot_eigenvalues",...) below because the argument handling is different */
573:     PetscCall(PetscOptionsDeprecated("-ksp_plot_eigenvalues", NULL, "3.9", "Use -ksp_view_eigenvalues draw"));
574:     PetscCall(PetscOptionsName("-ksp_plot_eigenvalues", "[deprecated since PETSc 3.9; use -ksp_view_eigenvalues draw]", "KSPView", &ksp->viewEV));
575:     if (ksp->viewEV) {
576:       ksp->formatEV = PETSC_VIEWER_DEFAULT;
577:       ksp->viewerEV = PETSC_VIEWER_DRAW_(comm);
578:       PetscCall(PetscObjectReference((PetscObject)ksp->viewerEV));
579:     }
580:   }
581:   if (!ksp->viewEV) {
582:     PetscCall(PetscOptionsDeprecated("-ksp_plot_eigenvalues_explicitly", NULL, "3.9", "Use -ksp_view_eigenvalues_explicit draw"));
583:     /* Cannot remove the what otherwise would be redundant call to PetscOptionsName("-ksp_plot_eigencontours",...) below because the argument handling is different */
584:     PetscCall(PetscOptionsName("-ksp_plot_eigencontours", "[deprecated since PETSc 3.9; use -ksp_view_eigenvalues draw::draw_contour]", "KSPView", &ksp->viewEV));
585:     if (ksp->viewEV) {
586:       ksp->formatEV = PETSC_VIEWER_DRAW_CONTOUR;
587:       ksp->viewerEV = PETSC_VIEWER_DRAW_(comm);
588:       PetscCall(PetscObjectReference((PetscObject)ksp->viewerEV));
589:     }
590:   }
591:   if (!ksp->viewEVExp) {
592:     /* Cannot remove the what otherwise would be redundant call to PetscOptionsName("-ksp_plot_eigencontours_explicitly",...) below because the argument handling is different */
593:     PetscCall(PetscOptionsName("-ksp_plot_eigenvalues_explicitly", "[deprecated since PETSc 3.9; use -ksp_view_eigenvalues_explicit draw]", "KSPView", &ksp->viewEVExp));
594:     if (ksp->viewEVExp) {
595:       ksp->formatEVExp = PETSC_VIEWER_DEFAULT;
596:       ksp->viewerEVExp = PETSC_VIEWER_DRAW_(comm);
597:       PetscCall(PetscObjectReference((PetscObject)ksp->viewerEVExp));
598:     }
599:   }

601: #if defined(PETSC_HAVE_SAWS)
602:   /*
603:     Publish convergence information using AMS
604:   */
605:   PetscCall(PetscOptionsBool("-ksp_monitor_saws", "Publish KSP progress using SAWs", "KSPMonitorSet", PETSC_FALSE, &flg, &set));
606:   if (set && flg) {
607:     void *ctx;
608:     PetscCall(KSPMonitorSAWsCreate(ksp, &ctx));
609:     PetscCall(KSPMonitorSet(ksp, KSPMonitorSAWs, ctx, KSPMonitorSAWsDestroy));
610:     PetscCall(KSPSetComputeSingularValues(ksp, PETSC_TRUE));
611:   }
612: #endif

614:   /* -----------------------------------------------------------------------*/
615:   PetscCall(KSPSetUpNorms_Private(ksp, PETSC_FALSE, NULL, &pcside));
616:   PetscCall(PetscOptionsEnum("-ksp_pc_side", "KSP preconditioner side", "KSPSetPCSide", PCSides, (PetscEnum)pcside, (PetscEnum *)&pcside, &flg));
617:   if (flg) PetscCall(KSPSetPCSide(ksp, pcside));

619:   if (ksp->viewSV || ksp->viewEV) PetscCall(KSPSetComputeSingularValues(ksp, PETSC_TRUE));

621: #if defined(PETSC_HAVE_SAWS)
622:   {
623:     PetscBool set;
624:     flg = PETSC_FALSE;
625:     PetscCall(PetscOptionsBool("-ksp_saws_block", "Block for SAWs at end of KSPSolve", "PetscObjectSAWsBlock", ((PetscObject)ksp)->amspublishblock, &flg, &set));
626:     if (set) PetscCall(PetscObjectSAWsSetBlock((PetscObject)ksp, flg));
627:   }
628: #endif

630:   nmax = ksp->nmax;
631:   PetscCall(PetscOptionsDeprecated("-ksp_matsolve_block_size", "-ksp_matsolve_batch_size", "3.15", NULL));
632:   PetscCall(PetscOptionsInt("-ksp_matsolve_batch_size", "Maximum number of columns treated simultaneously", "KSPSetMatSolveBatchSize", nmax, &nmax, &flg));
633:   if (flg) PetscCall(KSPSetMatSolveBatchSize(ksp, nmax));

635:   flg = PETSC_FALSE;
636:   PetscCall(PetscOptionsBool("-ksp_use_explicittranspose", "Explicitly transpose the system in KSPSolveTranspose", "KSPSetUseExplicitTranspose", ksp->transpose.use_explicittranspose, &flg, &set));
637:   if (set) PetscCall(KSPSetUseExplicitTranspose(ksp, flg));

639:   PetscTryTypeMethod(ksp, setfromoptions, PetscOptionsObject);
640: skipoptions:
641:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
642:   PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)ksp, PetscOptionsObject));
643:   PetscOptionsEnd();
644:   ksp->setfromoptionscalled++;
645:   PetscFunctionReturn(PETSC_SUCCESS);
646: }

648: /*@
649:   KSPResetFromOptions - Sets `KSP` parameters from user options ONLY if the `KSP` was previously set from options

651:   Collective

653:   Input Parameter:
654: . ksp - the `KSP` context

656:   Level: advanced

658: .seealso: [](ch_ksp), `KSPSetFromOptions()`, `KSPSetOptionsPrefix()`
659: @*/
660: PetscErrorCode KSPResetFromOptions(KSP ksp)
661: {
662:   PetscFunctionBegin;
663:   if (ksp->setfromoptionscalled) PetscCall(KSPSetFromOptions(ksp));
664:   PetscFunctionReturn(PETSC_SUCCESS);
665: }