Line data Source code
1 : /*
2 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3 : SLEPc - Scalable Library for Eigenvalue Problem Computations
4 : Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
5 :
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 options that can be set via the command-line
12 : or procedurally
13 : */
14 :
15 : #include <slepc/private/mfnimpl.h> /*I "slepcmfn.h" I*/
16 : #include <petscdraw.h>
17 :
18 : /*@C
19 : MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20 : indicated by the user.
21 :
22 : Collective
23 :
24 : Input Parameters:
25 : + mfn - the matrix function context
26 : . opt - the command line option for this monitor
27 : . name - the monitor type one is seeking
28 : - ctx - an optional user context for the monitor, or NULL
29 :
30 : Level: developer
31 :
32 : .seealso: MFNMonitorSet()
33 : @*/
34 17 : PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char opt[],const char name[],void *ctx)
35 : {
36 17 : PetscErrorCode (*mfunc)(MFN,PetscInt,PetscReal,void*);
37 17 : PetscErrorCode (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
38 17 : PetscErrorCode (*dfunc)(PetscViewerAndFormat**);
39 17 : PetscViewerAndFormat *vf;
40 17 : PetscViewer viewer;
41 17 : PetscViewerFormat format;
42 17 : PetscViewerType vtype;
43 17 : char key[PETSC_MAX_PATH_LEN];
44 17 : PetscBool flg;
45 :
46 17 : PetscFunctionBegin;
47 17 : PetscCall(PetscOptionsCreateViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,opt,&viewer,&format,&flg));
48 17 : if (!flg) PetscFunctionReturn(PETSC_SUCCESS);
49 :
50 1 : PetscCall(PetscViewerGetType(viewer,&vtype));
51 1 : PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
52 1 : PetscCall(PetscFunctionListFind(MFNMonitorList,key,&mfunc));
53 1 : PetscCheck(mfunc,PetscObjectComm((PetscObject)mfn),PETSC_ERR_SUP,"Specified viewer and format not supported");
54 1 : PetscCall(PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc));
55 1 : PetscCall(PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc));
56 1 : if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
57 1 : if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
58 :
59 1 : PetscCall((*cfunc)(viewer,format,ctx,&vf));
60 1 : PetscCall(PetscViewerDestroy(&viewer));
61 1 : PetscCall(MFNMonitorSet(mfn,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
62 1 : PetscFunctionReturn(PETSC_SUCCESS);
63 : }
64 :
65 : /*@
66 : MFNSetFromOptions - Sets MFN options from the options database.
67 : This routine must be called before MFNSetUp() if the user is to be
68 : allowed to set the solver type.
69 :
70 : Collective
71 :
72 : Input Parameters:
73 : . mfn - the matrix function context
74 :
75 : Notes:
76 : To see all options, run your program with the -help option.
77 :
78 : Level: beginner
79 :
80 : .seealso: MFNSetOptionsPrefix()
81 : @*/
82 17 : PetscErrorCode MFNSetFromOptions(MFN mfn)
83 : {
84 17 : char type[256];
85 17 : PetscBool set,flg,flg1,flg2;
86 17 : PetscReal r;
87 17 : PetscInt i;
88 :
89 17 : PetscFunctionBegin;
90 17 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
91 17 : PetscCall(MFNRegisterAll());
92 51 : PetscObjectOptionsBegin((PetscObject)mfn);
93 20 : PetscCall(PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,sizeof(type),&flg));
94 17 : if (flg) PetscCall(MFNSetType(mfn,type));
95 12 : else if (!((PetscObject)mfn)->type_name) PetscCall(MFNSetType(mfn,MFNKRYLOV));
96 :
97 17 : i = mfn->max_it;
98 17 : PetscCall(PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1));
99 17 : if (!flg1) i = PETSC_DETERMINE;
100 17 : r = mfn->tol;
101 30 : PetscCall(PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",SlepcDefaultTol(mfn->tol),&r,&flg2));
102 17 : if (flg1 || flg2) PetscCall(MFNSetTolerances(mfn,r,i));
103 :
104 17 : PetscCall(PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg));
105 17 : if (flg) PetscCall(MFNSetDimensions(mfn,i));
106 :
107 17 : PetscCall(PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL));
108 :
109 : /* -----------------------------------------------------------------------*/
110 : /*
111 : Cancels all monitors hardwired into code before call to MFNSetFromOptions()
112 : */
113 17 : PetscCall(PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set));
114 17 : if (set && flg) PetscCall(MFNMonitorCancel(mfn));
115 17 : PetscCall(MFNMonitorSetFromOptions(mfn,"-mfn_monitor","error_estimate",NULL));
116 :
117 : /* -----------------------------------------------------------------------*/
118 17 : PetscCall(PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",&set));
119 :
120 17 : PetscTryTypeMethod(mfn,setfromoptions,PetscOptionsObject);
121 17 : PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)mfn,PetscOptionsObject));
122 17 : PetscOptionsEnd();
123 :
124 17 : if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
125 17 : PetscCall(BVSetFromOptions(mfn->V));
126 17 : if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
127 17 : PetscCall(FNSetFromOptions(mfn->fn));
128 17 : PetscFunctionReturn(PETSC_SUCCESS);
129 : }
130 :
131 : /*@
132 : MFNGetTolerances - Gets the tolerance and maximum iteration count used
133 : by the MFN convergence tests.
134 :
135 : Not Collective
136 :
137 : Input Parameter:
138 : . mfn - the matrix function context
139 :
140 : Output Parameters:
141 : + tol - the convergence tolerance
142 : - maxits - maximum number of iterations
143 :
144 : Notes:
145 : The user can specify NULL for any parameter that is not needed.
146 :
147 : Level: intermediate
148 :
149 : .seealso: MFNSetTolerances()
150 : @*/
151 5 : PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
152 : {
153 5 : PetscFunctionBegin;
154 5 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
155 5 : if (tol) *tol = mfn->tol;
156 5 : if (maxits) *maxits = mfn->max_it;
157 5 : PetscFunctionReturn(PETSC_SUCCESS);
158 : }
159 :
160 : /*@
161 : MFNSetTolerances - Sets the tolerance and maximum iteration count used
162 : by the MFN convergence tests.
163 :
164 : Logically Collective
165 :
166 : Input Parameters:
167 : + mfn - the matrix function context
168 : . tol - the convergence tolerance
169 : - maxits - maximum number of iterations to use
170 :
171 : Options Database Keys:
172 : + -mfn_tol <tol> - Sets the convergence tolerance
173 : - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
174 :
175 : Notes:
176 : Use PETSC_CURRENT to retain the current value of any of the parameters.
177 : Use PETSC_DETERMINE for either argument to assign a default value computed
178 : internally (may be different in each solver).
179 : For maxits use PETSC_UMLIMITED to indicate there is no upper bound on this value.
180 :
181 : Level: intermediate
182 :
183 : .seealso: MFNGetTolerances()
184 : @*/
185 10 : PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
186 : {
187 10 : PetscFunctionBegin;
188 10 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
189 30 : PetscValidLogicalCollectiveReal(mfn,tol,2);
190 30 : PetscValidLogicalCollectiveInt(mfn,maxits,3);
191 10 : if (tol == (PetscReal)PETSC_DETERMINE) {
192 0 : mfn->tol = PETSC_DETERMINE;
193 0 : mfn->setupcalled = 0;
194 10 : } else if (tol != (PetscReal)PETSC_CURRENT) {
195 10 : PetscCheck(tol>0.0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
196 10 : mfn->tol = tol;
197 : }
198 10 : if (maxits == PETSC_DETERMINE) {
199 6 : mfn->max_it = PETSC_DETERMINE;
200 6 : mfn->setupcalled = 0;
201 4 : } else if (maxits == PETSC_UNLIMITED) {
202 0 : mfn->max_it = PETSC_INT_MAX;
203 4 : } else if (maxits != PETSC_CURRENT) {
204 3 : PetscCheck(maxits>0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
205 3 : mfn->max_it = maxits;
206 : }
207 10 : PetscFunctionReturn(PETSC_SUCCESS);
208 : }
209 :
210 : /*@
211 : MFNGetDimensions - Gets the dimension of the subspace used by the solver.
212 :
213 : Not Collective
214 :
215 : Input Parameter:
216 : . mfn - the matrix function context
217 :
218 : Output Parameter:
219 : . ncv - the maximum dimension of the subspace to be used by the solver
220 :
221 : Level: intermediate
222 :
223 : .seealso: MFNSetDimensions()
224 : @*/
225 4 : PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
226 : {
227 4 : PetscFunctionBegin;
228 4 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
229 4 : PetscAssertPointer(ncv,2);
230 4 : *ncv = mfn->ncv;
231 4 : PetscFunctionReturn(PETSC_SUCCESS);
232 : }
233 :
234 : /*@
235 : MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
236 :
237 : Logically Collective
238 :
239 : Input Parameters:
240 : + mfn - the matrix function context
241 : - ncv - the maximum dimension of the subspace to be used by the solver
242 :
243 : Options Database Keys:
244 : . -mfn_ncv <ncv> - Sets the dimension of the subspace
245 :
246 : Notes:
247 : Use PETSC_DETERMINE for ncv to assign a reasonably good value, which is
248 : dependent on the solution method.
249 :
250 : Level: intermediate
251 :
252 : .seealso: MFNGetDimensions()
253 : @*/
254 7 : PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
255 : {
256 7 : PetscFunctionBegin;
257 7 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
258 21 : PetscValidLogicalCollectiveInt(mfn,ncv,2);
259 7 : if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
260 0 : mfn->ncv = PETSC_DETERMINE;
261 : } else {
262 7 : PetscCheck(ncv>0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
263 7 : mfn->ncv = ncv;
264 : }
265 7 : mfn->setupcalled = 0;
266 7 : PetscFunctionReturn(PETSC_SUCCESS);
267 : }
268 :
269 : /*@
270 : MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
271 : solver has not converged.
272 :
273 : Logically Collective
274 :
275 : Input Parameters:
276 : + mfn - the matrix function context
277 : - flg - PETSC_TRUE indicates you want the error generated
278 :
279 : Options Database Keys:
280 : . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
281 :
282 : Level: intermediate
283 :
284 : Note:
285 : Normally SLEPc continues if the solver fails to converge, you can call
286 : MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
287 :
288 : .seealso: MFNGetErrorIfNotConverged()
289 : @*/
290 11 : PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
291 : {
292 11 : PetscFunctionBegin;
293 11 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
294 33 : PetscValidLogicalCollectiveBool(mfn,flg,2);
295 11 : mfn->errorifnotconverged = flg;
296 11 : PetscFunctionReturn(PETSC_SUCCESS);
297 : }
298 :
299 : /*@
300 : MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
301 : generate an error if the solver does not converge.
302 :
303 : Not Collective
304 :
305 : Input Parameter:
306 : . mfn - the matrix function context
307 :
308 : Output Parameter:
309 : . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
310 :
311 : Level: intermediate
312 :
313 : .seealso: MFNSetErrorIfNotConverged()
314 : @*/
315 2 : PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
316 : {
317 2 : PetscFunctionBegin;
318 2 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
319 2 : PetscAssertPointer(flag,2);
320 2 : *flag = mfn->errorifnotconverged;
321 2 : PetscFunctionReturn(PETSC_SUCCESS);
322 : }
323 :
324 : /*@
325 : MFNSetOptionsPrefix - Sets the prefix used for searching for all
326 : MFN options in the database.
327 :
328 : Logically Collective
329 :
330 : Input Parameters:
331 : + mfn - the matrix function context
332 : - prefix - the prefix string to prepend to all MFN option requests
333 :
334 : Notes:
335 : A hyphen (-) must NOT be given at the beginning of the prefix name.
336 : The first character of all runtime options is AUTOMATICALLY the
337 : hyphen.
338 :
339 : For example, to distinguish between the runtime options for two
340 : different MFN contexts, one could call
341 : .vb
342 : MFNSetOptionsPrefix(mfn1,"fun1_")
343 : MFNSetOptionsPrefix(mfn2,"fun2_")
344 : .ve
345 :
346 : Level: advanced
347 :
348 : .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
349 : @*/
350 1 : PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
351 : {
352 1 : PetscFunctionBegin;
353 1 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
354 1 : if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
355 1 : PetscCall(BVSetOptionsPrefix(mfn->V,prefix));
356 1 : if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
357 1 : PetscCall(FNSetOptionsPrefix(mfn->fn,prefix));
358 1 : PetscCall(PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix));
359 1 : PetscFunctionReturn(PETSC_SUCCESS);
360 : }
361 :
362 : /*@
363 : MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
364 : MFN options in the database.
365 :
366 : Logically Collective
367 :
368 : Input Parameters:
369 : + mfn - the matrix function context
370 : - prefix - the prefix string to prepend to all MFN option requests
371 :
372 : Notes:
373 : A hyphen (-) must NOT be given at the beginning of the prefix name.
374 : The first character of all runtime options is AUTOMATICALLY the hyphen.
375 :
376 : Level: advanced
377 :
378 : .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
379 : @*/
380 1 : PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
381 : {
382 1 : PetscFunctionBegin;
383 1 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
384 1 : if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
385 1 : PetscCall(BVAppendOptionsPrefix(mfn->V,prefix));
386 1 : if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
387 1 : PetscCall(FNAppendOptionsPrefix(mfn->fn,prefix));
388 1 : PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix));
389 1 : PetscFunctionReturn(PETSC_SUCCESS);
390 : }
391 :
392 : /*@
393 : MFNGetOptionsPrefix - Gets the prefix used for searching for all
394 : MFN options in the database.
395 :
396 : Not Collective
397 :
398 : Input Parameters:
399 : . mfn - the matrix function context
400 :
401 : Output Parameters:
402 : . prefix - pointer to the prefix string used is returned
403 :
404 : Note:
405 : On the Fortran side, the user should pass in a string 'prefix' of
406 : sufficient length to hold the prefix.
407 :
408 : Level: advanced
409 :
410 : .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
411 : @*/
412 1 : PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
413 : {
414 1 : PetscFunctionBegin;
415 1 : PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
416 1 : PetscAssertPointer(prefix,2);
417 1 : PetscCall(PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix));
418 1 : PetscFunctionReturn(PETSC_SUCCESS);
419 : }
|
