1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

  6:    This file is part of SLEPc.
  7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
  8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  9: */
 10: /*
 11:    MFN routines related to monitors
 12: */

 14: #include <slepc/private/mfnimpl.h>
 15: #include <petscdraw.h>

 17: /*
 18:    Runs the user provided monitor routines, if any.
 19: */
 20: PetscErrorCode MFNMonitor(MFN mfn,PetscInt it,PetscReal errest)
 21: {
 22:   PetscInt       i,n = mfn->numbermonitors;

 24:   PetscFunctionBegin;
 25:   for (i=0;i<n;i++) PetscCall((*mfn->monitor[i])(mfn,it,errest,mfn->monitorcontext[i]));
 26:   PetscFunctionReturn(PETSC_SUCCESS);
 27: }

 29: /*@C
 30:    MFNMonitorSet - Sets an ADDITIONAL function to be called at every
 31:    iteration to monitor convergence.

 33:    Logically Collective

 35:    Input Parameters:
 36: +  mfn     - matrix function context obtained from MFNCreate()
 37: .  monitor - pointer to function (if this is NULL, it turns off monitoring)
 38: .  mctx    - [optional] context for private data for the
 39:              monitor routine (use NULL if no context is desired)
 40: -  monitordestroy - [optional] routine that frees monitor context (may be NULL),
 41:              see PetscCtxDestroyFn for the calling sequence

 43:    Calling sequence of monitor:
 44: $  PetscErrorCode monitor(MFN mfn,PetscInt its,PetscReal errest,void *mctx)
 45: +  mfn    - matrix function context obtained from MFNCreate()
 46: .  its    - iteration number
 47: .  errest - error estimate
 48: -  mctx   - optional monitoring context, as set by MFNMonitorSet()

 50:    Options Database Keys:
 51: +    -mfn_monitor - print the error estimate
 52: .    -mfn_monitor draw::draw_lg - sets line graph monitor for the error estimate
 53: -    -mfn_monitor_cancel - cancels all monitors that have been hardwired into
 54:       a code by calls to MFNMonitorSet(), but does not cancel those set via
 55:       the options database.

 57:    Notes:
 58:    Several different monitoring routines may be set by calling
 59:    MFNMonitorSet() multiple times; all will be called in the
 60:    order in which they were set.

 62:    Level: intermediate

 64: .seealso: MFNMonitorCancel()
 65: @*/
 66: PetscErrorCode MFNMonitorSet(MFN mfn,PetscErrorCode (*monitor)(MFN mfn,PetscInt its,PetscReal errest,void *mctx),void *mctx,PetscCtxDestroyFn *monitordestroy)
 67: {
 68:   PetscFunctionBegin;
 70:   PetscCheck(mfn->numbermonitors<MAXMFNMONITORS,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Too many MFN monitors set");
 71:   mfn->monitor[mfn->numbermonitors]           = monitor;
 72:   mfn->monitorcontext[mfn->numbermonitors]    = (void*)mctx;
 73:   mfn->monitordestroy[mfn->numbermonitors++]  = monitordestroy;
 74:   PetscFunctionReturn(PETSC_SUCCESS);
 75: }

 77: /*@
 78:    MFNMonitorCancel - Clears all monitors for an MFN object.

 80:    Logically Collective

 82:    Input Parameters:
 83: .  mfn - matrix function context obtained from MFNCreate()

 85:    Options Database Key:
 86: .    -mfn_monitor_cancel - cancels all monitors that have been hardwired
 87:       into a code by calls to MFNMonitorSet(),
 88:       but does not cancel those set via the options database.

 90:    Level: intermediate

 92: .seealso: MFNMonitorSet()
 93: @*/
 94: PetscErrorCode MFNMonitorCancel(MFN mfn)
 95: {
 96:   PetscInt       i;

 98:   PetscFunctionBegin;
100:   for (i=0; i<mfn->numbermonitors; i++) {
101:     if (mfn->monitordestroy[i]) PetscCall((*mfn->monitordestroy[i])(&mfn->monitorcontext[i]));
102:   }
103:   mfn->numbermonitors = 0;
104:   PetscFunctionReturn(PETSC_SUCCESS);
105: }

107: /*@C
108:    MFNGetMonitorContext - Gets the monitor context, as set by
109:    MFNMonitorSet() for the FIRST monitor only.

111:    Not Collective

113:    Input Parameter:
114: .  mfn - matrix function context obtained from MFNCreate()

116:    Output Parameter:
117: .  ctx - monitor context

119:    Level: intermediate

121: .seealso: MFNMonitorSet()
122: @*/
123: PetscErrorCode MFNGetMonitorContext(MFN mfn,void *ctx)
124: {
125:   PetscFunctionBegin;
127:   *(void**)ctx = mfn->monitorcontext[0];
128:   PetscFunctionReturn(PETSC_SUCCESS);
129: }

131: /*@C
132:    MFNMonitorDefault - Print the error estimate of the current approximation at each
133:    iteration of the matrix function solver.

135:    Collective

137:    Input Parameters:
138: +  mfn    - matrix function context
139: .  its    - iteration number
140: .  errest - error estimate
141: -  vf     - viewer and format for monitoring

143:    Options Database Key:
144: .  -mfn_monitor - activates MFNMonitorDefault()

146:    Level: intermediate

148: .seealso: MFNMonitorSet()
149: @*/
150: PetscErrorCode MFNMonitorDefault(MFN mfn,PetscInt its,PetscReal errest,PetscViewerAndFormat *vf)
151: {
152:   PetscViewer    viewer = vf->viewer;

154:   PetscFunctionBegin;
157:   PetscCall(PetscViewerPushFormat(viewer,vf->format));
158:   PetscCall(PetscViewerASCIIAddTab(viewer,((PetscObject)mfn)->tablevel));
159:   if (its == 1 && ((PetscObject)mfn)->prefix) PetscCall(PetscViewerASCIIPrintf(viewer,"  Error estimates for %s solve.\n",((PetscObject)mfn)->prefix));
160:   PetscCall(PetscViewerASCIIPrintf(viewer,"%3" PetscInt_FMT " MFN Error estimate %14.12e\n",its,(double)errest));
161:   PetscCall(PetscViewerASCIISubtractTab(viewer,((PetscObject)mfn)->tablevel));
162:   PetscCall(PetscViewerPopFormat(viewer));
163:   PetscFunctionReturn(PETSC_SUCCESS);
164: }

166: /*@C
167:    MFNMonitorDefaultDrawLG - Plots the error estimate of the current approximation at each
168:    iteration of the matrix function solver.

170:    Collective

172:    Input Parameters:
173: +  mfn    - matrix function context
174: .  its    - iteration number
175: .  errest - error estimate
176: -  vf     - viewer and format for monitoring

178:    Options Database Key:
179: .  -mfn_monitor draw::draw_lg - activates MFNMonitorDefaultDrawLG()

181:    Level: intermediate

183: .seealso: MFNMonitorSet()
184: @*/
185: PetscErrorCode MFNMonitorDefaultDrawLG(MFN mfn,PetscInt its,PetscReal errest,PetscViewerAndFormat *vf)
186: {
187:   PetscViewer    viewer = vf->viewer;
188:   PetscDrawLG    lg;
189:   PetscReal      x,y;

191:   PetscFunctionBegin;
194:   PetscCall(PetscViewerPushFormat(viewer,vf->format));
195:   PetscCall(PetscViewerDrawGetDrawLG(viewer,0,&lg));
196:   if (its==1) {
197:     PetscCall(PetscDrawLGReset(lg));
198:     PetscCall(PetscDrawLGSetDimension(lg,1));
199:     PetscCall(PetscDrawLGSetLimits(lg,1,1.0,PetscLog10Real(mfn->tol)-2,0.0));
200:   }
201:   x = (PetscReal)its;
202:   if (errest > 0.0) y = PetscLog10Real(errest);
203:   else y = 0.0;
204:   PetscCall(PetscDrawLGAddPoint(lg,&x,&y));
205:   if (its <= 20 || !(its % 5) || mfn->reason) {
206:     PetscCall(PetscDrawLGDraw(lg));
207:     PetscCall(PetscDrawLGSave(lg));
208:   }
209:   PetscCall(PetscViewerPopFormat(viewer));
210:   PetscFunctionReturn(PETSC_SUCCESS);
211: }

213: /*@C
214:    MFNMonitorDefaultDrawLGCreate - Creates the plotter for the error estimate.

216:    Collective

218:    Input Parameters:
219: +  viewer - the viewer
220: .  format - the viewer format
221: -  ctx    - an optional user context

223:    Output Parameter:
224: .  vf     - the viewer and format context

226:    Level: intermediate

228: .seealso: MFNMonitorSet()
229: @*/
230: PetscErrorCode MFNMonitorDefaultDrawLGCreate(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **vf)
231: {
232:   PetscFunctionBegin;
233:   PetscCall(PetscViewerAndFormatCreate(viewer,format,vf));
234:   (*vf)->data = ctx;
235:   PetscCall(PetscViewerMonitorLGSetUp(viewer,NULL,"Error Estimate","Log Error Estimate",1,NULL,PETSC_DECIDE,PETSC_DECIDE,400,300));
236:   PetscFunctionReturn(PETSC_SUCCESS);
237: }