Actual source code: nepopts.c

slepc-3.6.1 2015-09-03
Report Typos and Errors
  1: /*
  2:       NEP routines related to options that can be set via the command-line
  3:       or procedurally.

  5:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  6:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  7:    Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain

  9:    This file is part of SLEPc.

 11:    SLEPc is free software: you can redistribute it and/or modify it under  the
 12:    terms of version 3 of the GNU Lesser General Public License as published by
 13:    the Free Software Foundation.

 15:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
 16:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
 17:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
 18:    more details.

 20:    You  should have received a copy of the GNU Lesser General  Public  License
 21:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
 22:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 23: */

 25: #include <slepc/private/nepimpl.h>       /*I "slepcnep.h" I*/

 29: /*@
 30:    NEPSetFromOptions - Sets NEP options from the options database.
 31:    This routine must be called before NEPSetUp() if the user is to be
 32:    allowed to set the solver type.

 34:    Collective on NEP

 36:    Input Parameters:
 37: .  nep - the nonlinear eigensolver context

 39:    Notes:
 40:    To see all options, run your program with the -help option.

 42:    Level: beginner
 43: @*/
 44: PetscErrorCode NEPSetFromOptions(NEP nep)
 45: {
 46:   PetscErrorCode   ierr;
 47:   char             type[256],monfilename[PETSC_MAX_PATH_LEN];
 48:   PetscBool        flg,flg1,flg2,flg3,flg4,flg5;
 49:   PetscReal        r1,r2,r3;
 50:   PetscScalar      s;
 51:   PetscInt         i,j,k;
 52:   PetscViewer      monviewer;
 53:   SlepcConvMonitor ctx;

 57:   NEPRegisterAll();
 58:   PetscObjectOptionsBegin((PetscObject)nep);
 59:     PetscOptionsFList("-nep_type","Nonlinear Eigenvalue Problem method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,256,&flg);
 60:     if (flg) {
 61:       NEPSetType(nep,type);
 62:     } else if (!((PetscObject)nep)->type_name) {
 63:       NEPSetType(nep,NEPRII);
 64:     }

 66:     PetscOptionsEnum("-nep_refine","Iterative refinement method","NEPSetRefine",NEPRefineTypes,(PetscEnum)nep->refine,(PetscEnum*)&nep->refine,NULL);

 68:     i = nep->npart;
 69:     PetscOptionsInt("-nep_refine_partitions","Number of partitions of the communicator for iterative refinement","NEPSetRefine",nep->npart,&i,&flg1);
 70:     r1 = nep->reftol;
 71:     PetscOptionsReal("-nep_refine_tol","Tolerance for iterative refinement","NEPSetRefine",nep->reftol,&r1,&flg2);
 72:     j = nep->rits;
 73:     PetscOptionsInt("-nep_refine_its","Maximum number of iterations for iterative refinement","NEPSetRefine",nep->rits,&j,&flg3);
 74:     if (flg1 || flg2 || flg3) {
 75:       NEPSetRefine(nep,nep->refine,i,r1,j);
 76:     }

 78:     i = nep->max_it? nep->max_it: PETSC_DEFAULT;
 79:     PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1);
 80:     j = nep->max_funcs? nep->max_funcs: PETSC_DEFAULT;
 81:     PetscOptionsInt("-nep_max_funcs","Maximum number of function evaluations","NEPSetTolerances",nep->max_funcs,&j,&flg2);
 82:     r1 = nep->abstol;
 83:     PetscOptionsReal("-nep_atol","Absolute tolerance for residual norm","NEPSetTolerances",nep->abstol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->abstol,&r1,&flg3);
 84:     r2 = nep->rtol;
 85:     PetscOptionsReal("-nep_rtol","Relative tolerance for residual norm","NEPSetTolerances",nep->rtol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->rtol,&r2,&flg4);
 86:     r3 = nep->stol;
 87:     PetscOptionsReal("-nep_stol","Relative tolerance for step length","NEPSetTolerances",nep->stol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->stol,&r3,&flg5);
 88:     if (flg1 || flg2 || flg3 || flg4 || flg5) {
 89:       NEPSetTolerances(nep,r1,r2,r3,i,j);
 90:     }

 92:     flg  = PETSC_FALSE;
 93:     PetscOptionsBool("-nep_convergence_default","Default (relative error) convergence test","NEPSetConvergenceTest",flg,&flg,NULL);
 94:     if (flg) {
 95:       NEPSetConvergenceTest(nep,NEPConvergedDefault,NULL,NULL);
 96:     }

 98:     i = nep->nev;
 99:     PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1);
100:     j = nep->ncv? nep->ncv: PETSC_DEFAULT;
101:     PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2);
102:     k = nep->mpd? nep->mpd: PETSC_DEFAULT;
103:     PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3);
104:     if (flg1 || flg2 || flg3) {
105:       NEPSetDimensions(nep,i,j,k);
106:     }

108:     i = 0;
109:     PetscOptionsInt("-nep_lag_preconditioner","Interval to rebuild preconditioner","NEPSetLagPreconditioner",nep->lag,&i,&flg);
110:     if (flg) { NEPSetLagPreconditioner(nep,i); }

112:     PetscOptionsBool("-nep_const_correction_tol","Constant correction tolerance for the linear solver","NEPSetConstCorrectionTol",nep->cctol,&nep->cctol,NULL);

114:     PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg);
115:     if (flg) {
116:       NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE);
117:       NEPSetTarget(nep,s);
118:     }

120:     /* -----------------------------------------------------------------------*/
121:     /*
122:       Cancels all monitors hardwired into code before call to NEPSetFromOptions()
123:     */
124:     flg = PETSC_FALSE;
125:     PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",flg,&flg,NULL);
126:     if (flg) {
127:       NEPMonitorCancel(nep);
128:     }
129:     /*
130:       Prints approximate eigenvalues and error estimates at each iteration
131:     */
132:     PetscOptionsString("-nep_monitor","Monitor first unconverged approximate eigenvalue and error estimate","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
133:     if (flg) {
134:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
135:       NEPMonitorSet(nep,NEPMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
136:     }
137:     PetscOptionsString("-nep_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
138:     if (flg) {
139:       PetscNew(&ctx);
140:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&ctx->viewer);
141:       NEPMonitorSet(nep,NEPMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
142:     }
143:     PetscOptionsString("-nep_monitor_all","Monitor approximate eigenvalues and error estimates","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
144:     if (flg) {
145:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
146:       NEPMonitorSet(nep,NEPMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
147:       NEPSetTrackAll(nep,PETSC_TRUE);
148:     }
149:     flg = PETSC_FALSE;
150:     PetscOptionsBool("-nep_monitor_lg","Monitor first unconverged approximate error estimate graphically","NEPMonitorSet",flg,&flg,NULL);
151:     if (flg) {
152:       NEPMonitorSet(nep,NEPMonitorLG,NULL,NULL);
153:     }
154:     flg = PETSC_FALSE;
155:     PetscOptionsBool("-nep_monitor_lg_all","Monitor error estimates graphically","NEPMonitorSet",flg,&flg,NULL);
156:     if (flg) {
157:       NEPMonitorSet(nep,NEPMonitorLGAll,NULL,NULL);
158:       NEPSetTrackAll(nep,PETSC_TRUE);
159:     }
160:   /* -----------------------------------------------------------------------*/

162:     PetscOptionsBoolGroupBegin("-nep_largest_magnitude","compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
163:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE); }
164:     PetscOptionsBoolGroup("-nep_smallest_magnitude","compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
165:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE); }
166:     PetscOptionsBoolGroup("-nep_largest_real","compute largest real parts","NEPSetWhichEigenpairs",&flg);
167:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL); }
168:     PetscOptionsBoolGroup("-nep_smallest_real","compute smallest real parts","NEPSetWhichEigenpairs",&flg);
169:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL); }
170:     PetscOptionsBoolGroup("-nep_largest_imaginary","compute largest imaginary parts","NEPSetWhichEigenpairs",&flg);
171:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY); }
172:     PetscOptionsBoolGroup("-nep_smallest_imaginary","compute smallest imaginary parts","NEPSetWhichEigenpairs",&flg);
173:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY); }
174:     PetscOptionsBoolGroup("-nep_target_magnitude","compute nearest eigenvalues to target","NEPSetWhichEigenpairs",&flg);
175:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE); }
176:     PetscOptionsBoolGroup("-nep_target_real","compute eigenvalues with real parts close to target","NEPSetWhichEigenpairs",&flg);
177:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL); }
178:     PetscOptionsBoolGroupEnd("-nep_target_imaginary","compute eigenvalues with imaginary parts close to target","NEPSetWhichEigenpairs",&flg);
179:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY); }

181:     PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",0);
182:     PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",0);
183:     PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",0);
184:     PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPReasonView",0);
185:     PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",0);
186:     PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",0);

188:     if (nep->ops->setfromoptions) {
189:       (*nep->ops->setfromoptions)(PetscOptionsObject,nep);
190:     }
191:     PetscObjectProcessOptionsHandlers((PetscObject)nep);
192:   PetscOptionsEnd();

194:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
195:   BVSetFromOptions(nep->V);
196:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
197:   RGSetFromOptions(nep->rg);
198:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
199:   DSSetFromOptions(nep->ds);
200:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
201:   KSPSetOperators(nep->ksp,nep->function,nep->function_pre);
202:   KSPSetFromOptions(nep->ksp);
203:   PetscRandomSetFromOptions(nep->rand);
204:   return(0);
205: }

209: /*@
210:    NEPGetTolerances - Gets the tolerance and maximum iteration count used
211:    by the NEP convergence tests.

213:    Not Collective

215:    Input Parameter:
216: .  nep - the nonlinear eigensolver context

218:    Output Parameters:
219: +  abstol - absolute convergence tolerance
220: .  rtol   - relative convergence tolerance
221: .  stol   - convergence tolerance in terms of the norm of the change in the
222:            solution between steps, || delta x || < stol*|| x ||
223: .  maxit  - maximum number of iterations
224: -  maxf   - maximum number of function evaluations

226:    Notes:
227:    The user can specify NULL for any parameter that is not needed.

229:    Level: intermediate

231: .seealso: NEPSetTolerances()
232: @*/
233: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *abstol,PetscReal *rtol,PetscReal *stol,PetscInt *maxit,PetscInt *maxf)
234: {
237:   if (abstol) *abstol = nep->abstol;
238:   if (rtol)   *rtol   = nep->rtol;
239:   if (stol)   *stol   = nep->stol;
240:   if (maxit)  *maxit  = nep->max_it;
241:   if (maxf)   *maxf   = nep->max_funcs;
242:   return(0);
243: }

247: /*@
248:    NEPSetTolerances - Sets various parameters used in convergence tests.

250:    Logically Collective on NEP

252:    Input Parameters:
253: +  nep    - the nonlinear eigensolver context
254: .  abstol - absolute convergence tolerance
255: .  rtol   - relative convergence tolerance
256: .  stol   - convergence tolerance in terms of the norm of the change in the
257:             solution between steps, || delta x || < stol*|| x ||
258: .  maxit  - maximum number of iterations
259: -  maxf   - maximum number of function evaluations

261:    Options Database Keys:
262: +    -nep_atol <abstol> - Sets abstol
263: .    -nep_rtol <rtol> - Sets rtol
264: .    -nep_stol <stol> - Sets stol
265: .    -nep_max_it <maxit> - Sets maxit
266: -    -nep_max_funcs <maxf> - Sets maxf

268:    Notes:
269:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

271:    Level: intermediate

273: .seealso: NEPGetTolerances()
274: @*/
275: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)
276: {
284:   if (abstol == PETSC_DEFAULT) {
285:     nep->abstol = PETSC_DEFAULT;
286:   } else {
287:     if (abstol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Absolute tolerance %g must be non-negative",(double)abstol);
288:     nep->abstol = abstol;
289:   }
290:   if (rtol == PETSC_DEFAULT) {
291:     nep->rtol = PETSC_DEFAULT;
292:   } else {
293:     if (rtol < 0.0 || 1.0 <= rtol) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Relative tolerance %g must be non-negative and less than 1.0",(double)rtol);
294:     nep->rtol = rtol;
295:   }
296:   if (stol == PETSC_DEFAULT) {
297:     nep->stol = PETSC_DEFAULT;
298:   } else {
299:     if (stol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Step tolerance %g must be non-negative",(double)stol);
300:     nep->stol = stol;
301:   }
302:   if (maxit == PETSC_DEFAULT || maxit == PETSC_DECIDE) {
303:     nep->max_it = 0;
304:     nep->state = NEP_STATE_INITIAL;
305:   } else {
306:     if (maxit < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of iterations %D must be non-negative",maxit);
307:     nep->max_it = maxit;
308:   }
309:   if (maxf == PETSC_DEFAULT || maxf == PETSC_DECIDE) {
310:     nep->max_it = 0;
311:     nep->state = NEP_STATE_INITIAL;
312:   } else {
313:     if (maxf < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of function evaluations %D must be non-negative",maxf);
314:     nep->max_funcs = maxf;
315:   }
316:   return(0);
317: }

321: /*@
322:    NEPGetDimensions - Gets the number of eigenvalues to compute
323:    and the dimension of the subspace.

325:    Not Collective

327:    Input Parameter:
328: .  nep - the nonlinear eigensolver context

330:    Output Parameters:
331: +  nev - number of eigenvalues to compute
332: .  ncv - the maximum dimension of the subspace to be used by the solver
333: -  mpd - the maximum dimension allowed for the projected problem

335:    Notes:
336:    The user can specify NULL for any parameter that is not needed.

338:    Level: intermediate

340: .seealso: NEPSetDimensions()
341: @*/
342: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
343: {
346:   if (nev) *nev = nep->nev;
347:   if (ncv) *ncv = nep->ncv;
348:   if (mpd) *mpd = nep->mpd;
349:   return(0);
350: }

354: /*@
355:    NEPSetDimensions - Sets the number of eigenvalues to compute
356:    and the dimension of the subspace.

358:    Logically Collective on NEP

360:    Input Parameters:
361: +  nep - the nonlinear eigensolver context
362: .  nev - number of eigenvalues to compute
363: .  ncv - the maximum dimension of the subspace to be used by the solver
364: -  mpd - the maximum dimension allowed for the projected problem

366:    Options Database Keys:
367: +  -nep_nev <nev> - Sets the number of eigenvalues
368: .  -nep_ncv <ncv> - Sets the dimension of the subspace
369: -  -nep_mpd <mpd> - Sets the maximum projected dimension

371:    Notes:
372:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
373:    dependent on the solution method.

375:    The parameters ncv and mpd are intimately related, so that the user is advised
376:    to set one of them at most. Normal usage is that
377:    (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
378:    (b) in cases where nev is large, the user sets mpd.

380:    The value of ncv should always be between nev and (nev+mpd), typically
381:    ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise
382:    a smaller value should be used.

384:    Level: intermediate

386: .seealso: NEPGetDimensions()
387: @*/
388: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
389: {
395:   if (nev<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
396:   nep->nev = nev;
397:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
398:     nep->ncv = 0;
399:   } else {
400:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
401:     nep->ncv = ncv;
402:   }
403:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
404:     nep->mpd = 0;
405:   } else {
406:     if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
407:     nep->mpd = mpd;
408:   }
409:   nep->state = NEP_STATE_INITIAL;
410:   return(0);
411: }

415: /*@
416:     NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
417:     to be sought.

419:     Logically Collective on NEP

421:     Input Parameters:
422: +   nep   - eigensolver context obtained from NEPCreate()
423: -   which - the portion of the spectrum to be sought

425:     Possible values:
426:     The parameter 'which' can have one of these values

428: +     NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
429: .     NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
430: .     NEP_LARGEST_REAL - largest real parts
431: .     NEP_SMALLEST_REAL - smallest real parts
432: .     NEP_LARGEST_IMAGINARY - largest imaginary parts
433: .     NEP_SMALLEST_IMAGINARY - smallest imaginary parts
434: .     NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
435: .     NEP_TARGET_REAL - eigenvalues with real part closest to target
436: -     NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target

438:     Options Database Keys:
439: +   -nep_largest_magnitude - Sets largest eigenvalues in magnitude
440: .   -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
441: .   -nep_largest_real - Sets largest real parts
442: .   -nep_smallest_real - Sets smallest real parts
443: .   -nep_largest_imaginary - Sets largest imaginary parts
444: .   -nep_smallest_imaginary - Sets smallest imaginary parts
445: .   -nep_target_magnitude - Sets eigenvalues closest to target
446: .   -nep_target_real - Sets real parts closest to target
447: -   -nep_target_imaginary - Sets imaginary parts closest to target

449:     Notes:
450:     Not all eigensolvers implemented in NEP account for all the possible values
451:     stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
452:     and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
453:     for eigenvalue selection.

455:     Level: intermediate

457: .seealso: NEPGetWhichEigenpairs(), NEPWhich
458: @*/
459: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)
460: {
464:   switch (which) {
465:     case NEP_LARGEST_MAGNITUDE:
466:     case NEP_SMALLEST_MAGNITUDE:
467:     case NEP_LARGEST_REAL:
468:     case NEP_SMALLEST_REAL:
469:     case NEP_LARGEST_IMAGINARY:
470:     case NEP_SMALLEST_IMAGINARY:
471:     case NEP_TARGET_MAGNITUDE:
472:     case NEP_TARGET_REAL:
473: #if defined(PETSC_USE_COMPLEX)
474:     case NEP_TARGET_IMAGINARY:
475: #endif
476:       if (nep->which != which) {
477:         nep->state = NEP_STATE_INITIAL;
478:         nep->which = which;
479:       }
480:       break;
481:     default:
482:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
483:   }
484:   return(0);
485: }

489: /*@
490:     NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
491:     sought.

493:     Not Collective

495:     Input Parameter:
496: .   nep - eigensolver context obtained from NEPCreate()

498:     Output Parameter:
499: .   which - the portion of the spectrum to be sought

501:     Notes:
502:     See NEPSetWhichEigenpairs() for possible values of 'which'.

504:     Level: intermediate

506: .seealso: NEPSetWhichEigenpairs(), NEPWhich
507: @*/
508: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
509: {
513:   *which = nep->which;
514:   return(0);
515: }

519: /*@
520:     NEPSetLagPreconditioner - Determines when the preconditioner is rebuilt in the
521:     nonlinear solve.

523:     Logically Collective on NEP

525:     Input Parameters:
526: +   nep - the NEP context
527: -   lag - 0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
528:           computed within the nonlinear iteration, 2 means every second time
529:           the Jacobian is built, etc.

531:     Options Database Keys:
532: .   -nep_lag_preconditioner <lag>

534:     Notes:
535:     The default is 1.
536:     The preconditioner is ALWAYS built in the first iteration of a nonlinear solve.

538:     Level: intermediate

540: .seealso: NEPGetLagPreconditioner()
541: @*/
542: PetscErrorCode NEPSetLagPreconditioner(NEP nep,PetscInt lag)
543: {
547:   if (lag<0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Lag must be non-negative");
548:   nep->lag = lag;
549:   return(0);
550: }

554: /*@
555:     NEPGetLagPreconditioner - Indicates how often the preconditioner is rebuilt.

557:     Not Collective

559:     Input Parameter:
560: .   nep - the NEP context

562:     Output Parameter:
563: .   lag - the lag parameter

565:     Level: intermediate

567: .seealso: NEPSetLagPreconditioner()
568: @*/
569: PetscErrorCode NEPGetLagPreconditioner(NEP nep,PetscInt *lag)
570: {
574:   *lag = nep->lag;
575:   return(0);
576: }

580: /*@
581:     NEPSetConstCorrectionTol - Sets a flag to keep the tolerance used
582:     in the linear solver constant.

584:     Logically Collective on NEP

586:     Input Parameters:
587: +   nep - the NEP context
588: -   cct - a boolean value

590:     Options Database Keys:
591: .   -nep_const_correction_tol <cct>

593:     Notes:
594:     By default, an exponentially decreasing tolerance is set in the KSP used
595:     within the nonlinear iteration, so that each Newton iteration requests
596:     better accuracy than the previous one. The constant correction tolerance
597:     flag stops this behaviour.

599:     Level: intermediate

601: .seealso: NEPGetConstCorrectionTol()
602: @*/
603: PetscErrorCode NEPSetConstCorrectionTol(NEP nep,PetscBool cct)
604: {
608:   nep->cctol = cct;
609:   return(0);
610: }

614: /*@
615:     NEPGetConstCorrectionTol - Returns the constant tolerance flag.

617:     Not Collective

619:     Input Parameter:
620: .   nep - the NEP context

622:     Output Parameter:
623: .   cct - the value of the constant tolerance flag

625:     Level: intermediate

627: .seealso: NEPSetConstCorrectionTol()
628: @*/
629: PetscErrorCode NEPGetConstCorrectionTol(NEP nep,PetscBool *cct)
630: {
634:   *cct = nep->cctol;
635:   return(0);
636: }

640: /*@C
641:     NEPSetConvergenceTest - Sets the function to be used to test convergence
642:     of the nonlinear iterative solution.

644:     Logically Collective on NEP

646:     Input Parameters:
647: +   nep     - the NEP context
648: .   func    - a pointer to the convergence test function
649: .   ctx     - [optional] context for private data for the convergence routine
650:               (may be NULL)
651: -   destroy - [optional] destructor for the context (may be NULL;
652:               PETSC_NULL_FUNCTION in Fortran)

654:     Calling Sequence of func:
655: $   func(NEP nep,PetscInt it,PetscReal xnorm,PetscReal snorm,PetscReal fnorm,NEPConvergedReason reason*,void *fctx)

657: +   nep    - the NEP context
658: .   it     - iteration number
659: .   xnorm  - norm of the current solution
660: .   snorm  - norm of the step (difference between two consecutive solutions)
661: .   fnorm  - norm of the function (residual)
662: .   reason - (output) result of the convergence test
663: -   fctx   - optional context, as set by NEPSetConvergenceTest()

665:     Level: advanced

667: .seealso: NEPSetTolerances()
668: @*/
669: PetscErrorCode NEPSetConvergenceTest(NEP nep,PetscErrorCode (*func)(NEP,PetscInt,PetscReal,PetscReal,PetscReal,NEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
670: {

675:   if (nep->convergeddestroy) {
676:     (*nep->convergeddestroy)(nep->convergedctx);
677:   }
678:   nep->converged        = func;
679:   nep->convergeddestroy = destroy;
680:   nep->convergedctx     = ctx;
681:   return(0);
682: }

686: /*@
687:    NEPSetTrackAll - Specifies if the solver must compute the residual of all
688:    approximate eigenpairs or not.

690:    Logically Collective on NEP

692:    Input Parameters:
693: +  nep      - the eigensolver context
694: -  trackall - whether compute all residuals or not

696:    Notes:
697:    If the user sets trackall=PETSC_TRUE then the solver explicitly computes
698:    the residual for each eigenpair approximation. Computing the residual is
699:    usually an expensive operation and solvers commonly compute the associated
700:    residual to the first unconverged eigenpair.
701:    The options '-nep_monitor_all' and '-nep_monitor_lg_all' automatically
702:    activate this option.

704:    Level: developer

706: .seealso: NEPGetTrackAll()
707: @*/
708: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
709: {
713:   nep->trackall = trackall;
714:   return(0);
715: }

719: /*@
720:    NEPGetTrackAll - Returns the flag indicating whether all residual norms must
721:    be computed or not.

723:    Not Collective

725:    Input Parameter:
726: .  nep - the eigensolver context

728:    Output Parameter:
729: .  trackall - the returned flag

731:    Level: developer

733: .seealso: NEPSetTrackAll()
734: @*/
735: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
736: {
740:   *trackall = nep->trackall;
741:   return(0);
742: }

746: /*@
747:    NEPSetRefine - Specifies the refinement type (and options) to be used
748:    after the solve.

750:    Logically Collective on NEP

752:    Input Parameters:
753: +  nep    - the nonlinear eigensolver context
754: .  refine - refinement type
755: .  npart  - number of partitions of the communicator
756: .  tol    - the convergence tolerance
757: -  its    - maximum number of refinement iterations

759:    Options Database Keys:
760: +  -nep_refine <type> - refinement type, one of <none,simple,multiple>
761: .  -nep_refine_partitions <n> - the number of partitions
762: .  -nep_refine_tol <tol> - the tolerance
763: -  -nep_refine_its <its> - number of iterations

765:    Notes:
766:    By default, iterative refinement is disabled, since it may be very
767:    costly. There are two possible refinement strategies: simple and multiple.
768:    The simple approach performs iterative refinement on each of the
769:    converged eigenpairs individually, whereas the multiple strategy works
770:    with the invariant pair as a whole, refining all eigenpairs simultaneously.
771:    The latter may be required for the case of multiple eigenvalues.

773:    In some cases, especially when using direct solvers within the
774:    iterative refinement method, it may be helpful for improved scalability
775:    to split the communicator in several partitions. The npart parameter
776:    indicates how many partitions to use (defaults to 1).

778:    The tol and its parameters specify the stopping criterion. In the simple
779:    method, refinement continues until the residual of each eigenpair is
780:    below the tolerance (tol defaults to the NEP tol, but may be set to a
781:    different value). In contrast, the multiple method simply performs its
782:    refinement iterations (just one by default).

784:    Level: intermediate

786: .seealso: NEPGetRefine()
787: @*/
788: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its)
789: {
791:   PetscMPIInt    size;

799:   nep->refine = refine;
800:   if (refine) {  /* process parameters only if not REFINE_NONE */
801:     if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
802:       nep->npart = 1;
803:     } else {
804:       MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size);
805:       if (npart<1 || npart>size) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
806:       nep->npart = npart;
807:     }
808:     if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
809:       nep->reftol = nep->rtol;
810:     } else {
811:       if (tol<=0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
812:       nep->reftol = tol;
813:     }
814:     if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
815:       nep->rits = PETSC_DEFAULT;
816:     } else {
817:       if (its<0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
818:       nep->rits = its;
819:     }
820:   }
821:   nep->state = NEP_STATE_INITIAL;
822:   return(0);
823: }

827: /*@
828:    NEPGetRefine - Gets the refinement strategy used by the NEP object, and the
829:    associated parameters.

831:    Not Collective

833:    Input Parameter:
834: .  nep - the nonlinear eigensolver context

836:    Output Parameters:
837: +  refine - refinement type
838: .  npart  - number of partitions of the communicator
839: .  tol    - the convergence tolerance
840: -  its    - maximum number of refinement iterations

842:    Level: intermediate

844:    Note:
845:    The user can specify NULL for any parameter that is not needed.

847: .seealso: NEPSetRefine()
848: @*/
849: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its)
850: {
853:   if (refine) *refine = nep->refine;
854:   if (npart)  *npart  = nep->npart;
855:   if (tol)    *tol    = nep->reftol;
856:   if (its)    *its    = nep->rits;
857:   return(0);
858: }

862: /*@C
863:    NEPSetOptionsPrefix - Sets the prefix used for searching for all
864:    NEP options in the database.

866:    Logically Collective on NEP

868:    Input Parameters:
869: +  nep - the nonlinear eigensolver context
870: -  prefix - the prefix string to prepend to all NEP option requests

872:    Notes:
873:    A hyphen (-) must NOT be given at the beginning of the prefix name.
874:    The first character of all runtime options is AUTOMATICALLY the
875:    hyphen.

877:    For example, to distinguish between the runtime options for two
878:    different NEP contexts, one could call
879: .vb
880:       NEPSetOptionsPrefix(nep1,"neig1_")
881:       NEPSetOptionsPrefix(nep2,"neig2_")
882: .ve

884:    Level: advanced

886: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
887: @*/
888: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)
889: {

894:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
895:   BVSetOptionsPrefix(nep->V,prefix);
896:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
897:   DSSetOptionsPrefix(nep->ds,prefix);
898:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
899:   RGSetOptionsPrefix(nep->rg,prefix);
900:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
901:   KSPSetOptionsPrefix(nep->ksp,prefix);
902:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
903:   PetscObjectSetOptionsPrefix((PetscObject)nep,prefix);
904:   return(0);
905: }

909: /*@C
910:    NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
911:    NEP options in the database.

913:    Logically Collective on NEP

915:    Input Parameters:
916: +  nep - the nonlinear eigensolver context
917: -  prefix - the prefix string to prepend to all NEP option requests

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

923:    Level: advanced

925: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
926: @*/
927: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)
928: {

933:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
934:   BVSetOptionsPrefix(nep->V,prefix);
935:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
936:   DSSetOptionsPrefix(nep->ds,prefix);
937:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
938:   RGSetOptionsPrefix(nep->rg,prefix);
939:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
940:   KSPSetOptionsPrefix(nep->ksp,prefix);
941:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
942:   PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix);
943:   return(0);
944: }

948: /*@C
949:    NEPGetOptionsPrefix - Gets the prefix used for searching for all
950:    NEP options in the database.

952:    Not Collective

954:    Input Parameters:
955: .  nep - the nonlinear eigensolver context

957:    Output Parameters:
958: .  prefix - pointer to the prefix string used is returned

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

963:    Level: advanced

965: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
966: @*/
967: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
968: {

974:   PetscObjectGetOptionsPrefix((PetscObject)nep,prefix);
975:   return(0);
976: }