16   PetscConvEstDestroy - Destroys a PETSc convergence estimator `PetscConvEst` object
21 . ce - The `PetscConvEst` object
32   if (--((PetscObject)*ce)->refct > 0) {  in PetscConvEstDestroy()
36   PetscCall(PetscFree3((*ce)->initGuess, (*ce)->exactSol, (*ce)->ctxs));  in PetscConvEstDestroy()
37   PetscCall(PetscFree2((*ce)->dofs, (*ce)->errors));  in PetscConvEstDestroy()
43 …PetscConvEstSetFromOptions - Sets a convergence estimator `PetscConvEst` object based on values in…
48 . ce - The `PetscConvEst` object
58 …scCall(PetscOptionsInt("-convest_num_refine", "The number of refinements for the convergence check…  in PetscConvEstSetFromOptions()
59 …scCall(PetscOptionsReal("-convest_refine_factor", "The increase in resolution in each dimension", …  in PetscConvEstSetFromOptions()
60 …tscCall(PetscOptionsBool("-convest_monitor", "Monitor the error for each convergence check", "Pets…  in PetscConvEstSetFromOptions()
61 …Call(PetscOptionsBool("-convest_no_refine", "Debugging flag to run on the same mesh each time", "P…  in PetscConvEstSetFromOptions()
67   PetscConvEstView - Views a `PetscConvEst` object
72 + ce     - The `PetscConvEst` object
73 - viewer - The `PetscViewer`
83   PetscCall(PetscViewerASCIIPrintf(viewer, "ConvEst with %" PetscInt_FMT " levels\n", ce->Nr + 1));  in PetscConvEstView()
88   PetscConvEstGetSolver - Gets the solver used to produce discrete solutions
93 . ce - The `PetscConvEst` object
96 . solver - The solver
107   *solver = ce->solver;  in PetscConvEstGetSolver()
112   PetscConvEstSetSolver - Sets the solver used to produce discrete solutions
117 + ce     - The `PetscConvEst` object
118 - solver - The solver, must be a `KSP`, `SNES`, or `TS` object with an attached `DM`/`DS`, that can…
129   ce->solver = solver;  in PetscConvEstSetSolver()
135 …PetscConvEstSetUp - After the solver is specified, create data structures needed for estimating co…
140 . ce - The `PetscConvEst` object
151   PetscCall(DMGetNumFields(ce->idm, &Nf));  in PetscConvEstSetUp()
152   ce->Nf = PetscMax(Nf, 1);  in PetscConvEstSetUp()
153   PetscCall(PetscMalloc2((ce->Nr + 1) * ce->Nf, &ce->dofs, (ce->Nr + 1) * ce->Nf, &ce->errors));  in PetscConvEstSetUp()
154   PetscCall(PetscCalloc3(ce->Nf, &ce->initGuess, ce->Nf, &ce->exactSol, ce->Nf, &ce->ctxs));  in PetscConvEstSetUp()
155   for (f = 0; f < Nf; ++f) ce->initGuess[f] = zero_private;  in PetscConvEstSetUp()
156   PetscCall(DMGetNumDS(ce->idm, &Nds));  in PetscConvEstSetUp()
164     PetscCall(DMGetRegionNumDS(ce->idm, s, &label, &fieldIS, &ds, NULL));  in PetscConvEstSetUp()
169       PetscCall(PetscDSGetExactSolution(ds, field, &ce->exactSol[field], &ce->ctxs[field]));  in PetscConvEstSetUp()
173 …for (f = 0; f < Nf; ++f) PetscCheck(ce->exactSol[f], PetscObjectComm((PetscObject)ce), PETSC_ERR_A…  in PetscConvEstSetUp()
177 PetscErrorCode PetscConvEstComputeInitialGuess(PetscConvEst ce, PetscInt r, DM dm, Vec u)  in PetscConvEstComputeInitialGuess()  argument
183   PetscUseTypeMethod(ce, initguess, r, dm, u);  in PetscConvEstComputeInitialGuess()
187 PetscErrorCode PetscConvEstComputeError(PetscConvEst ce, PetscInt r, DM dm, Vec u, PetscReal errors…  in PetscConvEstComputeError()  argument
194   PetscUseTypeMethod(ce, computeerror, r, dm, u, errors);  in PetscConvEstComputeError()
199   PetscConvEstMonitorDefault - Monitors the convergence estimation loop
204 + ce - The `PetscConvEst` object
205 - r  - The refinement level
208 . -convest_monitor - Activate the monitor
214 PetscErrorCode PetscConvEstMonitorDefault(PetscConvEst ce, PetscInt r)  in PetscConvEstMonitorDefault()  argument
220   if (ce->monitor) {  in PetscConvEstMonitorDefault()
221     PetscInt  *dofs   = &ce->dofs[r * ce->Nf];  in PetscConvEstMonitorDefault()
222     PetscReal *errors = &ce->errors[r * ce->Nf];  in PetscConvEstMonitorDefault()
226     if (ce->Nf > 1) PetscCall(PetscPrintf(comm, "["));  in PetscConvEstMonitorDefault()
227     for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstMonitorDefault()
231     if (ce->Nf > 1) PetscCall(PetscPrintf(comm, "]"));  in PetscConvEstMonitorDefault()
234     if (ce->Nf > 1) PetscCall(PetscPrintf(comm, "["));  in PetscConvEstMonitorDefault()
235     for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstMonitorDefault()
237       if (errors[f] < 1.0e-11) PetscCall(PetscPrintf(comm, "< 1e-11"));  in PetscConvEstMonitorDefault()
240     if (ce->Nf > 1) PetscCall(PetscPrintf(comm, "]"));  in PetscConvEstMonitorDefault()
251   PetscCall(PetscObjectGetClassId(ce->solver, &id));  in PetscConvEstSetSNES_Private()
253   PetscCall(SNESGetDM((SNES)ce->solver, &ce->idm));  in PetscConvEstSetSNES_Private()
257 static PetscErrorCode PetscConvEstInitGuessSNES_Private(PetscConvEst ce, PetscInt r, DM dm, Vec u)  in PetscConvEstInitGuessSNES_Private()  argument
260   PetscCall(DMProjectFunction(dm, 0.0, ce->initGuess, ce->ctxs, INSERT_VALUES, u));  in PetscConvEstInitGuessSNES_Private()
264 static PetscErrorCode PetscConvEstComputeErrorSNES_Private(PetscConvEst ce, PetscInt r, DM dm, Vec …  in PetscConvEstComputeErrorSNES_Private()  argument
270   PetscCall(DMComputeL2FieldDiff(dm, 0.0, ce->exactSol, ce->ctxs, u, errors));  in PetscConvEstComputeErrorSNES_Private()
272   PetscCall(PetscOptionsHasName(NULL, prefix, "-convest_error_view", &errorView));  in PetscConvEstComputeErrorSNES_Private()
299     PetscCall(VecViewFromOptions(e, NULL, "-convest_error_view"));  in PetscConvEstComputeErrorSNES_Private()
314   for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstSetJacobianNullSpace_Private()
335   SNES        snes = (SNES)ce->solver;  in PetscConvEstGetConvRateSNES_Private()
339   PetscInt    Nr = ce->Nr, r, f, dim, oldlevel, oldnlev;  in PetscConvEstGetConvRateSNES_Private()  local
343 …cCheck(ce->r == 2.0, PetscObjectComm((PetscObject)ce), PETSC_ERR_SUP, "Only refinement factor 2 is…  in PetscConvEstGetConvRateSNES_Private()
344   PetscCall(DMGetDimension(ce->idm, &dim));  in PetscConvEstGetConvRateSNES_Private()
345   PetscCall(DMGetApplicationContext(ce->idm, &ctx));  in PetscConvEstGetConvRateSNES_Private()
346   PetscCall(DMPlexSetRefinementUniform(ce->idm, PETSC_TRUE));  in PetscConvEstGetConvRateSNES_Private()
347   PetscCall(DMGetRefineLevel(ce->idm, &oldlevel));  in PetscConvEstGetConvRateSNES_Private()
350   dm[0] = ce->idm;  in PetscConvEstGetConvRateSNES_Private()
351   for (r = 0; r <= Nr; ++r) {  in PetscConvEstGetConvRateSNES_Private()
357 …tscCall(PetscSNPrintf(stageName, PETSC_MAX_PATH_LEN - 1, "ConvEst Refinement Level %" PetscInt_FMT…  in PetscConvEstGetConvRateSNES_Private()
361     if (r > 0) {  in PetscConvEstGetConvRateSNES_Private()
362       if (!ce->noRefine) {  in PetscConvEstGetConvRateSNES_Private()
363         PetscCall(DMRefine(dm[r - 1], MPI_COMM_NULL, &dm[r]));  in PetscConvEstGetConvRateSNES_Private()
364         PetscCall(DMSetCoarseDM(dm[r], dm[r - 1]));  in PetscConvEstGetConvRateSNES_Private()
368         PetscCall(DMClone(dm[r - 1], &dm[r]));  in PetscConvEstGetConvRateSNES_Private()
369         PetscCall(DMCopyDisc(dm[r - 1], dm[r]));  in PetscConvEstGetConvRateSNES_Private()
370         PetscCall(DMGetCoordinateDM(dm[r - 1], &cdm));  in PetscConvEstGetConvRateSNES_Private()
371         PetscCall(DMGetCoordinateDM(dm[r], &rcdm));  in PetscConvEstGetConvRateSNES_Private()
374       PetscCall(DMCopyTransform(ce->idm, dm[r]));  in PetscConvEstGetConvRateSNES_Private()
375       PetscCall(PetscObjectGetName((PetscObject)dm[r - 1], &dmname));  in PetscConvEstGetConvRateSNES_Private()
376       PetscCall(PetscObjectSetName((PetscObject)dm[r], dmname));  in PetscConvEstGetConvRateSNES_Private()
377       for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstGetConvRateSNES_Private()
380         PetscCall(DMGetNullSpaceConstructor(dm[r - 1], f, &nspconstr));  in PetscConvEstGetConvRateSNES_Private()
381         PetscCall(DMSetNullSpaceConstructor(dm[r], f, nspconstr));  in PetscConvEstGetConvRateSNES_Private()
384     PetscCall(DMViewFromOptions(dm[r], NULL, "-conv_dm_view"));  in PetscConvEstGetConvRateSNES_Private()
386     PetscCall(DMCreateGlobalVector(dm[r], &u));  in PetscConvEstGetConvRateSNES_Private()
387     PetscCall(DMGetField(dm[r], 0, NULL, &disc));  in PetscConvEstGetConvRateSNES_Private()
392     PetscCall(SNESSetDM(snes, dm[r]));  in PetscConvEstGetConvRateSNES_Private()
393     PetscCall(DMPlexSetSNESLocalFEM(dm[r], PETSC_FALSE, ctx));  in PetscConvEstGetConvRateSNES_Private()
394     PetscCall(DMPlexSetSNESVariableBounds(dm[r], snes));  in PetscConvEstGetConvRateSNES_Private()
399     PetscCall(PetscConvEstComputeInitialGuess(ce, r, dm[r], u));  in PetscConvEstGetConvRateSNES_Private()
401     PetscCall(PetscLogEventBegin(ce->event, ce, 0, 0, 0));  in PetscConvEstGetConvRateSNES_Private()
402     PetscCall(PetscConvEstComputeError(ce, r, dm[r], u, &ce->errors[r * ce->Nf]));  in PetscConvEstGetConvRateSNES_Private()
403     PetscCall(PetscLogEventEnd(ce->event, ce, 0, 0, 0));  in PetscConvEstGetConvRateSNES_Private()
404     for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstGetConvRateSNES_Private()
409       PetscCall(DMGetLocalSection(dm[r], &s));  in PetscConvEstGetConvRateSNES_Private()
412 …PetscCallMPI(MPIU_Allreduce(&lsize, &ce->dofs[r * ce->Nf + f], 1, MPIU_INT, MPI_SUM, PetscObjectCo…  in PetscConvEstGetConvRateSNES_Private()
413       PetscCall(PetscLogEventSetDof(ce->event, f, ce->dofs[r * ce->Nf + f]));  in PetscConvEstGetConvRateSNES_Private()
414       PetscCall(PetscLogEventSetError(ce->event, f, ce->errors[r * ce->Nf + f]));  in PetscConvEstGetConvRateSNES_Private()
417     PetscCall(PetscConvEstMonitorDefault(ce, r));  in PetscConvEstGetConvRateSNES_Private()
418     if (!r) {  in PetscConvEstGetConvRateSNES_Private()
431   for (r = 1; r <= Nr; ++r) PetscCall(DMDestroy(&dm[r]));  in PetscConvEstGetConvRateSNES_Private()
434   for (f = 0; f < ce->Nf; ++f) {  in PetscConvEstGetConvRateSNES_Private()
435     for (r = 0; r <= Nr; ++r) {  in PetscConvEstGetConvRateSNES_Private()
436       x[r] = PetscLog10Real(ce->dofs[r * ce->Nf + f]);  in PetscConvEstGetConvRateSNES_Private()
437       y[r] = PetscLog10Real(ce->errors[r * ce->Nf + f]);  in PetscConvEstGetConvRateSNES_Private()
440     /* Since h^{-dim} = N, lg err = s lg N + b = -s dim lg h + b */  in PetscConvEstGetConvRateSNES_Private()
441     alpha[f] = -slope * dim;  in PetscConvEstGetConvRateSNES_Private()
455 …PetscCall(DMSetRefineLevel(ce->idm, oldlevel)); /* The damn DMCoarsen() calls in PCMG can reset th…  in PetscConvEstGetConvRateSNES_Private()
457   PetscCall(SNESSetDM(snes, ce->idm));  in PetscConvEstGetConvRateSNES_Private()
458   PetscCall(DMPlexSetSNESLocalFEM(ce->idm, PETSC_FALSE, ctx));  in PetscConvEstGetConvRateSNES_Private()
459   PetscCall(DMPlexSetSNESVariableBounds(ce->idm, snes));  in PetscConvEstGetConvRateSNES_Private()
466   PetscConvEstGetConvRate - Returns an estimate of the convergence rate for the discretization
471 . ce - The `PetscConvEst` object
474 . alpha - The convergence rate for each field
477 + -snes_convergence_estimate - Execute convergence estimation inside `SNESSolve()` and print out th…
478 - -ts_convergence_estimate   - Execute convergence estimation inside `TSSolve()` and print out the …
486   || u_\Delta - u_{exact} || < C \Delta^\alpha
502 …if (ce->event < 0) PetscCall(PetscLogEventRegister("ConvEst Error", PETSC_OBJECT_CLASSID, &ce->eve…  in PetscConvEstGetConvRate()
503   for (f = 0; f < ce->Nf; ++f) alpha[f] = 0.0;  in PetscConvEstGetConvRate()
509 …PetscConvEstRateView - Displays the convergence rate obtained from `PetscConvEstGetConvRate()` usi…
514 + ce     - iterative context obtained from `SNESCreate()`
515 . alpha  - the convergence rate for each field
516 - viewer - the viewer to display the reason
519 . -snes_convergence_estimate - print the convergence rate
532     PetscInt Nf = ce->Nf, f;  in PetscConvEstRateView()
534     PetscCall(PetscViewerASCIIAddTab(viewer, ((PetscObject)ce)->tablevel));  in PetscConvEstRateView()
543     PetscCall(PetscViewerASCIISubtractTab(viewer, ((PetscObject)ce)->tablevel));  in PetscConvEstRateView()
549 …PetscConvEstCreate - Create a `PetscConvEst` object. This is used to study the convergence rate of…
554 . comm - The communicator for the `PetscConvEst` object
557 . ce - The `PetscConvEst` object
569   (*ce)->monitor           = PETSC_FALSE;  in PetscConvEstCreate()
570   (*ce)->r                 = 2.0;  in PetscConvEstCreate()
571   (*ce)->Nr                = 4;  in PetscConvEstCreate()
572   (*ce)->event             = -1;  in PetscConvEstCreate()
573   (*ce)->ops->setsolver    = PetscConvEstSetSNES_Private;  in PetscConvEstCreate()
574   (*ce)->ops->initguess    = PetscConvEstInitGuessSNES_Private;  in PetscConvEstCreate()
575   (*ce)->ops->computeerror = PetscConvEstComputeErrorSNES_Private;  in PetscConvEstCreate()
576   (*ce)->ops->getconvrate  = PetscConvEstGetConvRateSNES_Private;  in PetscConvEstCreate()