Actual source code: epsopts.c

slepc-main 2024-11-09
Report Typos and Errors
  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:    EPS routines related to options that can be set via the command-line
 12:    or procedurally.
 13: */

 15: #include <slepc/private/epsimpl.h>
 16: #include <petscdraw.h>

 18: /*@C
 19:    EPSMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
 20:    indicated by the user.

 22:    Collective

 24:    Input Parameters:
 25: +  eps      - the eigensolver 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: -  trackall - whether this monitor tracks all eigenvalues or not

 31:    Level: developer

 33: .seealso: EPSMonitorSet(), EPSSetTrackAll()
 34: @*/
 35: PetscErrorCode EPSMonitorSetFromOptions(EPS eps,const char opt[],const char name[],void *ctx,PetscBool trackall)
 36: {
 37:   PetscErrorCode       (*mfunc)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
 38:   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
 39:   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
 40:   PetscViewerAndFormat *vf;
 41:   PetscViewer          viewer;
 42:   PetscViewerFormat    format;
 43:   PetscViewerType      vtype;
 44:   char                 key[PETSC_MAX_PATH_LEN];
 45:   PetscBool            flg;

 47:   PetscFunctionBegin;
 48:   PetscCall(PetscOptionsCreateViewer(PetscObjectComm((PetscObject)eps),((PetscObject)eps)->options,((PetscObject)eps)->prefix,opt,&viewer,&format,&flg));
 49:   if (!flg) PetscFunctionReturn(PETSC_SUCCESS);

 51:   PetscCall(PetscViewerGetType(viewer,&vtype));
 52:   PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
 53:   PetscCall(PetscFunctionListFind(EPSMonitorList,key,&mfunc));
 54:   PetscCheck(mfunc,PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"Specified viewer and format not supported");
 55:   PetscCall(PetscFunctionListFind(EPSMonitorCreateList,key,&cfunc));
 56:   PetscCall(PetscFunctionListFind(EPSMonitorDestroyList,key,&dfunc));
 57:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
 58:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

 60:   PetscCall((*cfunc)(viewer,format,ctx,&vf));
 61:   PetscCall(PetscViewerDestroy(&viewer));
 62:   PetscCall(EPSMonitorSet(eps,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
 63:   if (trackall) PetscCall(EPSSetTrackAll(eps,PETSC_TRUE));
 64:   PetscFunctionReturn(PETSC_SUCCESS);
 65: }

 67: /*@
 68:    EPSSetFromOptions - Sets EPS options from the options database.
 69:    This routine must be called before EPSSetUp() if the user is to be
 70:    allowed to set the solver type.

 72:    Collective

 74:    Input Parameters:
 75: .  eps - the eigensolver context

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

 80:    Level: beginner

 82: .seealso: EPSSetOptionsPrefix()
 83: @*/
 84: PetscErrorCode EPSSetFromOptions(EPS eps)
 85: {
 86:   char           type[256];
 87:   PetscBool      set,flg,flg1,flg2,flg3,bval;
 88:   PetscReal      r,array[2]={0,0};
 89:   PetscScalar    s;
 90:   PetscInt       i,j,k;
 91:   EPSBalance     bal;

 93:   PetscFunctionBegin;
 95:   PetscCall(EPSRegisterAll());
 96:   PetscObjectOptionsBegin((PetscObject)eps);
 97:     PetscCall(PetscOptionsFList("-eps_type","Eigensolver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,sizeof(type),&flg));
 98:     if (flg) PetscCall(EPSSetType(eps,type));
 99:     else if (!((PetscObject)eps)->type_name) PetscCall(EPSSetType(eps,EPSKRYLOVSCHUR));

101:     PetscCall(PetscOptionsBoolGroupBegin("-eps_hermitian","Hermitian eigenvalue problem","EPSSetProblemType",&flg));
102:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_HEP));
103:     PetscCall(PetscOptionsBoolGroup("-eps_gen_hermitian","Generalized Hermitian eigenvalue problem","EPSSetProblemType",&flg));
104:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_GHEP));
105:     PetscCall(PetscOptionsBoolGroup("-eps_non_hermitian","Non-Hermitian eigenvalue problem","EPSSetProblemType",&flg));
106:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_NHEP));
107:     PetscCall(PetscOptionsBoolGroup("-eps_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem","EPSSetProblemType",&flg));
108:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_GNHEP));
109:     PetscCall(PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","Generalized non-Hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg));
110:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_PGNHEP));
111:     PetscCall(PetscOptionsBoolGroup("-eps_gen_indefinite","Generalized Hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg));
112:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_GHIEP));
113:     PetscCall(PetscOptionsBoolGroupEnd("-eps_bse","Structured Bethe-Salpeter eigenvalue problem","EPSSetProblemType",&flg));
114:     if (flg) PetscCall(EPSSetProblemType(eps,EPS_BSE));

116:     PetscCall(PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg));
117:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_RITZ));
118:     PetscCall(PetscOptionsBoolGroup("-eps_harmonic","Harmonic Ritz extraction","EPSSetExtraction",&flg));
119:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC));
120:     PetscCall(PetscOptionsBoolGroup("-eps_harmonic_relative","Relative harmonic Ritz extraction","EPSSetExtraction",&flg));
121:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE));
122:     PetscCall(PetscOptionsBoolGroup("-eps_harmonic_right","Right harmonic Ritz extraction","EPSSetExtraction",&flg));
123:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_RIGHT));
124:     PetscCall(PetscOptionsBoolGroup("-eps_harmonic_largest","Largest harmonic Ritz extraction","EPSSetExtraction",&flg));
125:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_HARMONIC_LARGEST));
126:     PetscCall(PetscOptionsBoolGroup("-eps_refined","Refined Ritz extraction","EPSSetExtraction",&flg));
127:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_REFINED));
128:     PetscCall(PetscOptionsBoolGroupEnd("-eps_refined_harmonic","Refined harmonic Ritz extraction","EPSSetExtraction",&flg));
129:     if (flg) PetscCall(EPSSetExtraction(eps,EPS_REFINED_HARMONIC));

131:     bal = eps->balance;
132:     PetscCall(PetscOptionsEnum("-eps_balance","Balancing method","EPSSetBalance",EPSBalanceTypes,(PetscEnum)bal,(PetscEnum*)&bal,&flg1));
133:     j = eps->balance_its;
134:     PetscCall(PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,&flg2));
135:     r = eps->balance_cutoff;
136:     PetscCall(PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,&flg3));
137:     if (flg1 || flg2 || flg3) PetscCall(EPSSetBalance(eps,bal,j,r));

139:     i = eps->max_it;
140:     PetscCall(PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,&flg1));
141:     r = eps->tol;
142:     PetscCall(PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",SlepcDefaultTol(eps->tol),&r,&flg2));
143:     if (flg1 || flg2) PetscCall(EPSSetTolerances(eps,r,i));

145:     PetscCall(PetscOptionsBoolGroupBegin("-eps_conv_rel","Relative error convergence test","EPSSetConvergenceTest",&flg));
146:     if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_REL));
147:     PetscCall(PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg));
148:     if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_NORM));
149:     PetscCall(PetscOptionsBoolGroup("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg));
150:     if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_ABS));
151:     PetscCall(PetscOptionsBoolGroupEnd("-eps_conv_user","User-defined convergence test","EPSSetConvergenceTest",&flg));
152:     if (flg) PetscCall(EPSSetConvergenceTest(eps,EPS_CONV_USER));

154:     PetscCall(PetscOptionsBoolGroupBegin("-eps_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","EPSSetStoppingTest",&flg));
155:     if (flg) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_BASIC));
156:     PetscCall(PetscOptionsBoolGroupEnd("-eps_stop_user","User-defined stopping test","EPSSetStoppingTest",&flg));
157:     if (flg) PetscCall(EPSSetStoppingTest(eps,EPS_STOP_USER));

159:     i = eps->nev;
160:     PetscCall(PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,&flg1));
161:     j = eps->ncv;
162:     PetscCall(PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,&flg2));
163:     k = eps->mpd;
164:     PetscCall(PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,&flg3));
165:     if (flg1 || flg2 || flg3) PetscCall(EPSSetDimensions(eps,i,j,k));

167:     PetscCall(PetscOptionsBoolGroupBegin("-eps_largest_magnitude","Compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg));
168:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE));
169:     PetscCall(PetscOptionsBoolGroup("-eps_smallest_magnitude","Compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg));
170:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE));
171:     PetscCall(PetscOptionsBoolGroup("-eps_largest_real","Compute eigenvalues with largest real parts","EPSSetWhichEigenpairs",&flg));
172:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL));
173:     PetscCall(PetscOptionsBoolGroup("-eps_smallest_real","Compute eigenvalues with smallest real parts","EPSSetWhichEigenpairs",&flg));
174:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL));
175:     PetscCall(PetscOptionsBoolGroup("-eps_largest_imaginary","Compute eigenvalues with largest imaginary parts","EPSSetWhichEigenpairs",&flg));
176:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY));
177:     PetscCall(PetscOptionsBoolGroup("-eps_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","EPSSetWhichEigenpairs",&flg));
178:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY));
179:     PetscCall(PetscOptionsBoolGroup("-eps_target_magnitude","Compute eigenvalues closest to target","EPSSetWhichEigenpairs",&flg));
180:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE));
181:     PetscCall(PetscOptionsBoolGroup("-eps_target_real","Compute eigenvalues with real parts closest to target","EPSSetWhichEigenpairs",&flg));
182:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL));
183:     PetscCall(PetscOptionsBoolGroup("-eps_target_imaginary","Compute eigenvalues with imaginary parts closest to target","EPSSetWhichEigenpairs",&flg));
184:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY));
185:     PetscCall(PetscOptionsBoolGroupEnd("-eps_all","Compute all eigenvalues in an interval or a region","EPSSetWhichEigenpairs",&flg));
186:     if (flg) PetscCall(EPSSetWhichEigenpairs(eps,EPS_ALL));

188:     PetscCall(PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg));
189:     if (flg) {
190:       if (eps->which!=EPS_TARGET_REAL && eps->which!=EPS_TARGET_IMAGINARY) PetscCall(EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE));
191:       PetscCall(EPSSetTarget(eps,s));
192:     }

194:     k = 2;
195:     PetscCall(PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg));
196:     if (flg) {
197:       PetscCheck(k>1,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");
198:       PetscCall(EPSSetWhichEigenpairs(eps,EPS_ALL));
199:       PetscCall(EPSSetInterval(eps,array[0],array[1]));
200:     }

202:     PetscCall(PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&eps->trueres,NULL));
203:     PetscCall(PetscOptionsBool("-eps_purify","Postprocess eigenvectors for purification","EPSSetPurify",eps->purify,&bval,&flg));
204:     if (flg) PetscCall(EPSSetPurify(eps,bval));
205:     PetscCall(PetscOptionsBool("-eps_two_sided","Use two-sided variant (to compute left eigenvectors)","EPSSetTwoSided",eps->twosided,&bval,&flg));
206:     if (flg) PetscCall(EPSSetTwoSided(eps,bval));

208:     /* -----------------------------------------------------------------------*/
209:     /*
210:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
211:     */
212:     PetscCall(PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",PETSC_FALSE,&flg,&set));
213:     if (set && flg) PetscCall(EPSMonitorCancel(eps));
214:     PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor","first_approximation",NULL,PETSC_FALSE));
215:     PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor_all","all_approximations",NULL,PETSC_TRUE));
216:     PetscCall(EPSMonitorSetFromOptions(eps,"-eps_monitor_conv","convergence_history",NULL,PETSC_FALSE));

218:     /* -----------------------------------------------------------------------*/
219:     PetscCall(PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",&set));
220:     PetscCall(PetscOptionsName("-eps_view_vectors","View computed eigenvectors","EPSVectorsView",&set));
221:     PetscCall(PetscOptionsName("-eps_view_values","View computed eigenvalues","EPSValuesView",&set));
222:     PetscCall(PetscOptionsName("-eps_converged_reason","Print reason for convergence, and number of iterations","EPSConvergedReasonView",&set));
223:     PetscCall(PetscOptionsName("-eps_error_absolute","Print absolute errors of each eigenpair","EPSErrorView",&set));
224:     PetscCall(PetscOptionsName("-eps_error_relative","Print relative errors of each eigenpair","EPSErrorView",&set));
225:     PetscCall(PetscOptionsName("-eps_error_backward","Print backward errors of each eigenpair","EPSErrorView",&set));

227:     PetscTryTypeMethod(eps,setfromoptions,PetscOptionsObject);
228:     PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)eps,PetscOptionsObject));
229:   PetscOptionsEnd();

231:   if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
232:   PetscCall(BVSetFromOptions(eps->V));
233:   if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
234:   PetscCall(RGSetFromOptions(eps->rg));
235:   if (eps->useds) {
236:     if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
237:     PetscCall(EPSSetDSType(eps));
238:     PetscCall(DSSetFromOptions(eps->ds));
239:   }
240:   if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
241:   PetscCall(EPSSetDefaultST(eps));
242:   PetscCall(STSetFromOptions(eps->st));
243:   PetscFunctionReturn(PETSC_SUCCESS);
244: }

246: /*@
247:    EPSGetTolerances - Gets the tolerance and maximum iteration count used
248:    by the EPS convergence tests.

250:    Not Collective

252:    Input Parameter:
253: .  eps - the eigensolver context

255:    Output Parameters:
256: +  tol - the convergence tolerance
257: -  maxits - maximum number of iterations

259:    Notes:
260:    The user can specify NULL for any parameter that is not needed.

262:    Level: intermediate

264: .seealso: EPSSetTolerances()
265: @*/
266: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
267: {
268:   PetscFunctionBegin;
270:   if (tol)    *tol    = eps->tol;
271:   if (maxits) *maxits = eps->max_it;
272:   PetscFunctionReturn(PETSC_SUCCESS);
273: }

275: /*@
276:    EPSSetTolerances - Sets the tolerance and maximum iteration count used
277:    by the EPS convergence tests.

279:    Logically Collective

281:    Input Parameters:
282: +  eps - the eigensolver context
283: .  tol - the convergence tolerance
284: -  maxits - maximum number of iterations to use

286:    Options Database Keys:
287: +  -eps_tol <tol> - Sets the convergence tolerance
288: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

290:    Notes:
291:    Use PETSC_CURRENT to retain the current value of any of the parameters.
292:    Use PETSC_DETERMINE for either argument to assign a default value computed
293:    internally (may be different in each solver).
294:    For maxits use PETSC_UMLIMITED to indicate there is no upper bound on this value.

296:    Level: intermediate

298: .seealso: EPSGetTolerances()
299: @*/
300: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
301: {
302:   PetscFunctionBegin;
306:   if (tol == (PetscReal)PETSC_DETERMINE) {
307:     eps->tol   = PETSC_DETERMINE;
308:     eps->state = EPS_STATE_INITIAL;
309:   } else if (tol != (PetscReal)PETSC_CURRENT) {
310:     PetscCheck(tol>0.0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
311:     eps->tol = tol;
312:   }
313:   if (maxits == PETSC_DETERMINE) {
314:     eps->max_it = PETSC_DETERMINE;
315:     eps->state  = EPS_STATE_INITIAL;
316:   } else if (maxits == PETSC_UNLIMITED) {
317:     eps->max_it = PETSC_INT_MAX;
318:   } else if (maxits != PETSC_CURRENT) {
319:     PetscCheck(maxits>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
320:     eps->max_it = maxits;
321:   }
322:   PetscFunctionReturn(PETSC_SUCCESS);
323: }

325: /*@
326:    EPSGetDimensions - Gets the number of eigenvalues to compute
327:    and the dimension of the subspace.

329:    Not Collective

331:    Input Parameter:
332: .  eps - the eigensolver context

334:    Output Parameters:
335: +  nev - number of eigenvalues to compute
336: .  ncv - the maximum dimension of the subspace to be used by the solver
337: -  mpd - the maximum dimension allowed for the projected problem

339:    Level: intermediate

341: .seealso: EPSSetDimensions()
342: @*/
343: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
344: {
345:   PetscFunctionBegin;
347:   if (nev) *nev = eps->nev;
348:   if (ncv) *ncv = eps->ncv;
349:   if (mpd) *mpd = eps->mpd;
350:   PetscFunctionReturn(PETSC_SUCCESS);
351: }

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

357:    Logically Collective

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

365:    Options Database Keys:
366: +  -eps_nev <nev> - Sets the number of eigenvalues
367: .  -eps_ncv <ncv> - Sets the dimension of the subspace
368: -  -eps_mpd <mpd> - Sets the maximum projected dimension

370:    Notes:
371:    Use PETSC_DETERMINE for ncv and mpd to assign a reasonably good value, which is
372:    dependent on the solution method. For any of the arguments, use PETSC_CURRENT
373:    to preserve the current value.

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:    When computing all eigenvalues in an interval, see EPSSetInterval(), these
385:    parameters lose relevance, and tuning must be done with
386:    EPSKrylovSchurSetDimensions().

388:    Level: intermediate

390: .seealso: EPSGetDimensions(), EPSSetInterval(), EPSKrylovSchurSetDimensions()
391: @*/
392: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
393: {
394:   PetscFunctionBegin;
399:   if (nev != PETSC_CURRENT) {
400:     PetscCheck(nev>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
401:     eps->nev = nev;
402:   }
403:   if (ncv == PETSC_DETERMINE) {
404:     eps->ncv = PETSC_DETERMINE;
405:   } else if (ncv != PETSC_CURRENT) {
406:     PetscCheck(ncv>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
407:     eps->ncv = ncv;
408:   }
409:   if (mpd == PETSC_DETERMINE) {
410:     eps->mpd = PETSC_DETERMINE;
411:   } else if (mpd != PETSC_CURRENT) {
412:     PetscCheck(mpd>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
413:     eps->mpd = mpd;
414:   }
415:   eps->state = EPS_STATE_INITIAL;
416:   PetscFunctionReturn(PETSC_SUCCESS);
417: }

419: /*@
420:    EPSSetWhichEigenpairs - Specifies which portion of the spectrum is
421:    to be sought.

423:    Logically Collective

425:    Input Parameters:
426: +  eps   - eigensolver context obtained from EPSCreate()
427: -  which - the portion of the spectrum to be sought

429:    Options Database Keys:
430: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
431: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
432: .   -eps_largest_real - Sets largest real parts
433: .   -eps_smallest_real - Sets smallest real parts
434: .   -eps_largest_imaginary - Sets largest imaginary parts
435: .   -eps_smallest_imaginary - Sets smallest imaginary parts
436: .   -eps_target_magnitude - Sets eigenvalues closest to target
437: .   -eps_target_real - Sets real parts closest to target
438: .   -eps_target_imaginary - Sets imaginary parts closest to target
439: -   -eps_all - Sets all eigenvalues in an interval or region

441:    Notes:
442:    The parameter 'which' can have one of these values

444: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
445: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
446: .     EPS_LARGEST_REAL - largest real parts
447: .     EPS_SMALLEST_REAL - smallest real parts
448: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
449: .     EPS_SMALLEST_IMAGINARY - smallest imaginary parts
450: .     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
451: .     EPS_TARGET_REAL - eigenvalues with real part closest to target
452: .     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
453: .     EPS_ALL - all eigenvalues contained in a given interval or region
454: -     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

456:    Not all eigensolvers implemented in EPS account for all the possible values
457:    stated above. Also, some values make sense only for certain types of
458:    problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
459:    and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part
460:    for eigenvalue selection.

462:    The target is a scalar value provided with EPSSetTarget().

464:    The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and
465:    SLEPc have been built with complex scalars.

467:    EPS_ALL is intended for use in combination with an interval (see
468:    EPSSetInterval()), when all eigenvalues within the interval are requested,
469:    or in the context of the CISS solver for computing all eigenvalues in a region.
470:    In those cases, the number of eigenvalues is unknown, so the nev parameter
471:    has a different sense, see EPSSetDimensions().

473:    Level: intermediate

475: .seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),
476:           EPSSetDimensions(), EPSSetEigenvalueComparison(), EPSWhich
477: @*/
478: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
479: {
480:   PetscFunctionBegin;
483:   switch (which) {
484:     case EPS_LARGEST_MAGNITUDE:
485:     case EPS_SMALLEST_MAGNITUDE:
486:     case EPS_LARGEST_REAL:
487:     case EPS_SMALLEST_REAL:
488:     case EPS_LARGEST_IMAGINARY:
489:     case EPS_SMALLEST_IMAGINARY:
490:     case EPS_TARGET_MAGNITUDE:
491:     case EPS_TARGET_REAL:
492: #if defined(PETSC_USE_COMPLEX)
493:     case EPS_TARGET_IMAGINARY:
494: #endif
495:     case EPS_ALL:
496:     case EPS_WHICH_USER:
497:       if (eps->which != which) {
498:         eps->state = EPS_STATE_INITIAL;
499:         eps->which = which;
500:       }
501:       break;
502: #if !defined(PETSC_USE_COMPLEX)
503:     case EPS_TARGET_IMAGINARY:
504:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_SUP,"EPS_TARGET_IMAGINARY can be used only with complex scalars");
505: #endif
506:     default:
507:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
508:   }
509:   PetscFunctionReturn(PETSC_SUCCESS);
510: }

512: /*@
513:    EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be
514:    sought.

516:    Not Collective

518:    Input Parameter:
519: .  eps - eigensolver context obtained from EPSCreate()

521:    Output Parameter:
522: .  which - the portion of the spectrum to be sought

524:    Notes:
525:    See EPSSetWhichEigenpairs() for possible values of 'which'.

527:    Level: intermediate

529: .seealso: EPSSetWhichEigenpairs(), EPSWhich
530: @*/
531: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
532: {
533:   PetscFunctionBegin;
535:   PetscAssertPointer(which,2);
536:   *which = eps->which;
537:   PetscFunctionReturn(PETSC_SUCCESS);
538: }

540: /*@C
541:    EPSSetEigenvalueComparison - Specifies the eigenvalue comparison function
542:    when EPSSetWhichEigenpairs() is set to EPS_WHICH_USER.

544:    Logically Collective

546:    Input Parameters:
547: +  eps  - eigensolver context obtained from EPSCreate()
548: .  func - the comparison function, see EPSEigenvalueComparisonFn for the calling sequence
549: -  ctx  - a context pointer (the last parameter to the comparison function)

551:    Note:
552:    The returning parameter 'res' can be
553: +  negative - if the 1st eigenvalue is preferred to the 2st one
554: .  zero     - if both eigenvalues are equally preferred
555: -  positive - if the 2st eigenvalue is preferred to the 1st one

557:    Level: advanced

559: .seealso: EPSSetWhichEigenpairs(), EPSWhich
560: @*/
561: PetscErrorCode EPSSetEigenvalueComparison(EPS eps,SlepcEigenvalueComparisonFn *func,void* ctx)
562: {
563:   PetscFunctionBegin;
565:   eps->sc->comparison    = func;
566:   eps->sc->comparisonctx = ctx;
567:   eps->which             = EPS_WHICH_USER;
568:   PetscFunctionReturn(PETSC_SUCCESS);
569: }

571: /*@C
572:    EPSSetArbitrarySelection - Specifies a function intended to look for
573:    eigenvalues according to an arbitrary selection criterion. This criterion
574:    can be based on a computation involving the current eigenvector approximation.

576:    Logically Collective

578:    Input Parameters:
579: +  eps  - eigensolver context obtained from EPSCreate()
580: .  func - the arbitrary selection function, see SlepcArbitrarySelectionFn for a calling sequence
581: -  ctx  - a context pointer (the last parameter to the arbitrary selection function)

583:    Notes:
584:    This provides a mechanism to select eigenpairs by evaluating a user-defined
585:    function. When a function has been provided, the default selection based on
586:    sorting the eigenvalues is replaced by the sorting of the results of this
587:    function (with the same sorting criterion given in EPSSetWhichEigenpairs()).

589:    For instance, suppose you want to compute those eigenvectors that maximize
590:    a certain computable expression. Then implement the computation using
591:    the arguments xr and xi, and return the result in rr. Then set the standard
592:    sorting by magnitude so that the eigenpair with largest value of rr is
593:    selected.

595:    This evaluation function is collective, that is, all processes call it and
596:    it can use collective operations; furthermore, the computed result must
597:    be the same in all processes.

599:    The result of func is expressed as a complex number so that it is possible to
600:    use the standard eigenvalue sorting functions, but normally only rr is used.
601:    Set ri to zero unless it is meaningful in your application.

603:    Level: advanced

605: .seealso: EPSSetWhichEigenpairs()
606: @*/
607: PetscErrorCode EPSSetArbitrarySelection(EPS eps,SlepcArbitrarySelectionFn *func,void* ctx)
608: {
609:   PetscFunctionBegin;
611:   eps->arbitrary    = func;
612:   eps->arbitraryctx = ctx;
613:   eps->state        = EPS_STATE_INITIAL;
614:   PetscFunctionReturn(PETSC_SUCCESS);
615: }

617: /*@C
618:    EPSSetConvergenceTestFunction - Sets a function to compute the error estimate
619:    used in the convergence test.

621:    Logically Collective

623:    Input Parameters:
624: +  eps     - eigensolver context obtained from EPSCreate()
625: .  func    - convergence test function, see EPSConvergenceTestFn for the calling sequence
626: .  ctx     - context for private data for the convergence routine (may be NULL)
627: -  destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence

629:    Note:
630:    If the error estimate returned by the convergence test function is less than
631:    the tolerance, then the eigenvalue is accepted as converged.

633:    Level: advanced

635: .seealso: EPSSetConvergenceTest(), EPSSetTolerances()
636: @*/
637: PetscErrorCode EPSSetConvergenceTestFunction(EPS eps,EPSConvergenceTestFn *func,void* ctx,PetscCtxDestroyFn *destroy)
638: {
639:   PetscFunctionBegin;
641:   if (eps->convergeddestroy) PetscCall((*eps->convergeddestroy)(&eps->convergedctx));
642:   eps->convergeduser    = func;
643:   eps->convergeddestroy = destroy;
644:   eps->convergedctx     = ctx;
645:   if (func == EPSConvergedRelative) eps->conv = EPS_CONV_REL;
646:   else if (func == EPSConvergedNorm) eps->conv = EPS_CONV_NORM;
647:   else if (func == EPSConvergedAbsolute) eps->conv = EPS_CONV_ABS;
648:   else {
649:     eps->conv      = EPS_CONV_USER;
650:     eps->converged = eps->convergeduser;
651:   }
652:   PetscFunctionReturn(PETSC_SUCCESS);
653: }

655: /*@
656:    EPSSetConvergenceTest - Specifies how to compute the error estimate
657:    used in the convergence test.

659:    Logically Collective

661:    Input Parameters:
662: +  eps  - eigensolver context obtained from EPSCreate()
663: -  conv - the type of convergence test

665:    Options Database Keys:
666: +  -eps_conv_abs  - Sets the absolute convergence test
667: .  -eps_conv_rel  - Sets the convergence test relative to the eigenvalue
668: .  -eps_conv_norm - Sets the convergence test relative to the matrix norms
669: -  -eps_conv_user - Selects the user-defined convergence test

671:    Note:
672:    The parameter 'conv' can have one of these values
673: +     EPS_CONV_ABS  - absolute error ||r||
674: .     EPS_CONV_REL  - error relative to the eigenvalue l, ||r||/|l|
675: .     EPS_CONV_NORM - error relative to the matrix norms, ||r||/(||A||+|l|*||B||)
676: -     EPS_CONV_USER - function set by EPSSetConvergenceTestFunction()

678:    Level: intermediate

680: .seealso: EPSGetConvergenceTest(), EPSSetConvergenceTestFunction(), EPSSetStoppingTest(), EPSConv
681: @*/
682: PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv)
683: {
684:   PetscFunctionBegin;
687:   switch (conv) {
688:     case EPS_CONV_ABS:  eps->converged = EPSConvergedAbsolute; break;
689:     case EPS_CONV_REL:  eps->converged = EPSConvergedRelative; break;
690:     case EPS_CONV_NORM: eps->converged = EPSConvergedNorm; break;
691:     case EPS_CONV_USER:
692:       PetscCheck(eps->convergeduser,PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetConvergenceTestFunction() first");
693:       eps->converged = eps->convergeduser;
694:       break;
695:     default:
696:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
697:   }
698:   eps->conv = conv;
699:   PetscFunctionReturn(PETSC_SUCCESS);
700: }

702: /*@
703:    EPSGetConvergenceTest - Gets the method used to compute the error estimate
704:    used in the convergence test.

706:    Not Collective

708:    Input Parameters:
709: .  eps   - eigensolver context obtained from EPSCreate()

711:    Output Parameters:
712: .  conv  - the type of convergence test

714:    Level: intermediate

716: .seealso: EPSSetConvergenceTest(), EPSConv
717: @*/
718: PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv)
719: {
720:   PetscFunctionBegin;
722:   PetscAssertPointer(conv,2);
723:   *conv = eps->conv;
724:   PetscFunctionReturn(PETSC_SUCCESS);
725: }

727: /*@C
728:    EPSSetStoppingTestFunction - Sets a function to decide when to stop the outer
729:    iteration of the eigensolver.

731:    Logically Collective

733:    Input Parameters:
734: +  eps     - eigensolver context obtained from EPSCreate()
735: .  func    - stopping test function, see EPSStoppingTestFn for the calling sequence
736: .  ctx     - context for private data for the stopping routine (may be NULL)
737: -  destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence

739:    Note:
740:    Normal usage is to first call the default routine EPSStoppingBasic() and then
741:    set reason to EPS_CONVERGED_USER if some user-defined conditions have been
742:    met. To let the eigensolver continue iterating, the result must be left as
743:    EPS_CONVERGED_ITERATING.

745:    Level: advanced

747: .seealso: EPSSetStoppingTest(), EPSStoppingBasic()
748: @*/
749: PetscErrorCode EPSSetStoppingTestFunction(EPS eps,EPSStoppingTestFn *func,void* ctx,PetscCtxDestroyFn *destroy)
750: {
751:   PetscFunctionBegin;
753:   if (eps->stoppingdestroy) PetscCall((*eps->stoppingdestroy)(&eps->stoppingctx));
754:   eps->stoppinguser    = func;
755:   eps->stoppingdestroy = destroy;
756:   eps->stoppingctx     = ctx;
757:   if (func == EPSStoppingBasic) eps->stop = EPS_STOP_BASIC;
758:   else {
759:     eps->stop     = EPS_STOP_USER;
760:     eps->stopping = eps->stoppinguser;
761:   }
762:   PetscFunctionReturn(PETSC_SUCCESS);
763: }

765: /*@
766:    EPSSetStoppingTest - Specifies how to decide the termination of the outer
767:    loop of the eigensolver.

769:    Logically Collective

771:    Input Parameters:
772: +  eps  - eigensolver context obtained from EPSCreate()
773: -  stop - the type of stopping test

775:    Options Database Keys:
776: +  -eps_stop_basic - Sets the default stopping test
777: -  -eps_stop_user  - Selects the user-defined stopping test

779:    Note:
780:    The parameter 'stop' can have one of these values
781: +     EPS_STOP_BASIC - default stopping test
782: -     EPS_STOP_USER  - function set by EPSSetStoppingTestFunction()

784:    Level: advanced

786: .seealso: EPSGetStoppingTest(), EPSSetStoppingTestFunction(), EPSSetConvergenceTest(), EPSStop
787: @*/
788: PetscErrorCode EPSSetStoppingTest(EPS eps,EPSStop stop)
789: {
790:   PetscFunctionBegin;
793:   switch (stop) {
794:     case EPS_STOP_BASIC: eps->stopping = EPSStoppingBasic; break;
795:     case EPS_STOP_USER:
796:       PetscCheck(eps->stoppinguser,PetscObjectComm((PetscObject)eps),PETSC_ERR_ORDER,"Must call EPSSetStoppingTestFunction() first");
797:       eps->stopping = eps->stoppinguser;
798:       break;
799:     default:
800:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
801:   }
802:   eps->stop = stop;
803:   PetscFunctionReturn(PETSC_SUCCESS);
804: }

806: /*@
807:    EPSGetStoppingTest - Gets the method used to decide the termination of the outer
808:    loop of the eigensolver.

810:    Not Collective

812:    Input Parameters:
813: .  eps   - eigensolver context obtained from EPSCreate()

815:    Output Parameters:
816: .  stop  - the type of stopping test

818:    Level: advanced

820: .seealso: EPSSetStoppingTest(), EPSStop
821: @*/
822: PetscErrorCode EPSGetStoppingTest(EPS eps,EPSStop *stop)
823: {
824:   PetscFunctionBegin;
826:   PetscAssertPointer(stop,2);
827:   *stop = eps->stop;
828:   PetscFunctionReturn(PETSC_SUCCESS);
829: }

831: /*@
832:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

834:    Logically Collective

836:    Input Parameters:
837: +  eps      - the eigensolver context
838: -  type     - a known type of eigenvalue problem

840:    Options Database Keys:
841: +  -eps_hermitian - Hermitian eigenvalue problem
842: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
843: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
844: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
845: .  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem
846:    with positive semi-definite B
847: .  -eps_gen_indefinite - generalized Hermitian-indefinite eigenvalue problem
848: -  -eps_bse - structured Bethe-Salpeter eigenvalue problem

850:    Notes:
851:    This function must be used to instruct SLEPc to exploit symmetry or other
852:    kind of structure. If no
853:    problem type is specified, by default a non-Hermitian problem is assumed
854:    (either standard or generalized). If the user knows that the problem is
855:    Hermitian (i.e. A=A^H) or generalized Hermitian (i.e. A=A^H, B=B^H, and
856:    B positive definite) then it is recommended to set the problem type so
857:    that eigensolver can exploit these properties.

859:    If the user does not call this function, the solver will use a reasonable
860:    guess.

862:    For structured problem types such as EPS_BSE, the matrices passed in via
863:    EPSSetOperators() must have been created with the corresponding helper
864:    function, i.e., MatCreateBSE().

866:    Level: intermediate

868: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
869: @*/
870: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
871: {
872:   PetscFunctionBegin;
875:   if (type == eps->problem_type) PetscFunctionReturn(PETSC_SUCCESS);
876:   switch (type) {
877:     case EPS_HEP:
878:       eps->isgeneralized = PETSC_FALSE;
879:       eps->ishermitian = PETSC_TRUE;
880:       eps->ispositive = PETSC_FALSE;
881:       eps->isstructured = PETSC_FALSE;
882:       break;
883:     case EPS_NHEP:
884:       eps->isgeneralized = PETSC_FALSE;
885:       eps->ishermitian = PETSC_FALSE;
886:       eps->ispositive = PETSC_FALSE;
887:       eps->isstructured = PETSC_FALSE;
888:       break;
889:     case EPS_GHEP:
890:       eps->isgeneralized = PETSC_TRUE;
891:       eps->ishermitian = PETSC_TRUE;
892:       eps->ispositive = PETSC_TRUE;
893:       eps->isstructured = PETSC_FALSE;
894:       break;
895:     case EPS_GNHEP:
896:       eps->isgeneralized = PETSC_TRUE;
897:       eps->ishermitian = PETSC_FALSE;
898:       eps->ispositive = PETSC_FALSE;
899:       eps->isstructured = PETSC_FALSE;
900:       break;
901:     case EPS_PGNHEP:
902:       eps->isgeneralized = PETSC_TRUE;
903:       eps->ishermitian = PETSC_FALSE;
904:       eps->ispositive = PETSC_TRUE;
905:       eps->isstructured = PETSC_FALSE;
906:       break;
907:     case EPS_GHIEP:
908:       eps->isgeneralized = PETSC_TRUE;
909:       eps->ishermitian = PETSC_TRUE;
910:       eps->ispositive = PETSC_FALSE;
911:       eps->isstructured = PETSC_FALSE;
912:       break;
913:     case EPS_BSE:
914:       eps->isgeneralized = PETSC_FALSE;
915:       eps->ishermitian = PETSC_FALSE;
916:       eps->ispositive = PETSC_FALSE;
917:       eps->isstructured = PETSC_TRUE;
918:       break;
919:     default:
920:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
921:   }
922:   eps->problem_type = type;
923:   eps->state = EPS_STATE_INITIAL;
924:   PetscFunctionReturn(PETSC_SUCCESS);
925: }

927: /*@
928:    EPSGetProblemType - Gets the problem type from the EPS object.

930:    Not Collective

932:    Input Parameter:
933: .  eps - the eigensolver context

935:    Output Parameter:
936: .  type - the problem type

938:    Level: intermediate

940: .seealso: EPSSetProblemType(), EPSProblemType
941: @*/
942: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
943: {
944:   PetscFunctionBegin;
946:   PetscAssertPointer(type,2);
947:   *type = eps->problem_type;
948:   PetscFunctionReturn(PETSC_SUCCESS);
949: }

951: /*@
952:    EPSSetExtraction - Specifies the type of extraction technique to be employed
953:    by the eigensolver.

955:    Logically Collective

957:    Input Parameters:
958: +  eps  - the eigensolver context
959: -  extr - a known type of extraction

961:    Options Database Keys:
962: +  -eps_ritz - Rayleigh-Ritz extraction
963: .  -eps_harmonic - harmonic Ritz extraction
964: .  -eps_harmonic_relative - harmonic Ritz extraction relative to the eigenvalue
965: .  -eps_harmonic_right - harmonic Ritz extraction for rightmost eigenvalues
966: .  -eps_harmonic_largest - harmonic Ritz extraction for largest magnitude
967:    (without target)
968: .  -eps_refined - refined Ritz extraction
969: -  -eps_refined_harmonic - refined harmonic Ritz extraction

971:    Notes:
972:    Not all eigensolvers support all types of extraction. See the SLEPc
973:    Users Manual for details.

975:    By default, a standard Rayleigh-Ritz extraction is used. Other extractions
976:    may be useful when computing interior eigenvalues.

978:    Harmonic-type extractions are used in combination with a 'target'.

980:    Level: advanced

982: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
983: @*/
984: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
985: {
986:   PetscFunctionBegin;
989:   if (eps->extraction != extr) {
990:     eps->state      = EPS_STATE_INITIAL;
991:     eps->extraction = extr;
992:   }
993:   PetscFunctionReturn(PETSC_SUCCESS);
994: }

996: /*@
997:    EPSGetExtraction - Gets the extraction type used by the EPS object.

999:    Not Collective

1001:    Input Parameter:
1002: .  eps - the eigensolver context

1004:    Output Parameter:
1005: .  extr - name of extraction type

1007:    Level: advanced

1009: .seealso: EPSSetExtraction(), EPSExtraction
1010: @*/
1011: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
1012: {
1013:   PetscFunctionBegin;
1015:   PetscAssertPointer(extr,2);
1016:   *extr = eps->extraction;
1017:   PetscFunctionReturn(PETSC_SUCCESS);
1018: }

1020: /*@
1021:    EPSSetBalance - Specifies the balancing technique to be employed by the
1022:    eigensolver, and some parameters associated to it.

1024:    Logically Collective

1026:    Input Parameters:
1027: +  eps    - the eigensolver context
1028: .  bal    - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
1029:             EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
1030: .  its    - number of iterations of the balancing algorithm
1031: -  cutoff - cutoff value

1033:    Options Database Keys:
1034: +  -eps_balance <method> - the balancing method, where <method> is one of
1035:                            'none', 'oneside', 'twoside', or 'user'
1036: .  -eps_balance_its <its> - number of iterations
1037: -  -eps_balance_cutoff <cutoff> - cutoff value

1039:    Notes:
1040:    When balancing is enabled, the solver works implicitly with matrix DAD^-1,
1041:    where D is an appropriate diagonal matrix. This improves the accuracy of
1042:    the computed results in some cases. See the SLEPc Users Manual for details.

1044:    Balancing makes sense only for non-Hermitian problems when the required
1045:    precision is high (i.e. a small tolerance such as 1e-15).

1047:    By default, balancing is disabled. The two-sided method is much more
1048:    effective than the one-sided counterpart, but it requires the system
1049:    matrices to have the MatMultTranspose operation defined.

1051:    The parameter 'its' is the number of iterations performed by the method. The
1052:    cutoff value is used only in the two-side variant. Use PETSC_DETERMINE to assign
1053:    a reasonably good value, or PETSC_CURRENT to leave the value unchanged.

1055:    User-defined balancing is allowed provided that the corresponding matrix
1056:    is set via STSetBalanceMatrix.

1058:    Level: intermediate

1060: .seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
1061: @*/
1062: PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
1063: {
1064:   PetscFunctionBegin;
1069:   switch (bal) {
1070:     case EPS_BALANCE_NONE:
1071:     case EPS_BALANCE_ONESIDE:
1072:     case EPS_BALANCE_TWOSIDE:
1073:     case EPS_BALANCE_USER:
1074:       if (eps->balance != bal) {
1075:         eps->state = EPS_STATE_INITIAL;
1076:         eps->balance = bal;
1077:       }
1078:       break;
1079:     default:
1080:       SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
1081:   }
1082:   if (its==PETSC_DETERMINE) eps->balance_its = 5;
1083:   else if (its!=PETSC_CURRENT) {
1084:     PetscCheck(its>0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
1085:     eps->balance_its = its;
1086:   }
1087:   if (cutoff==(PetscReal)PETSC_DETERMINE) eps->balance_cutoff = 1e-8;
1088:   else if (cutoff!=(PetscReal)PETSC_CURRENT) {
1089:     PetscCheck(cutoff>0.0,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
1090:     eps->balance_cutoff = cutoff;
1091:   }
1092:   PetscFunctionReturn(PETSC_SUCCESS);
1093: }

1095: /*@
1096:    EPSGetBalance - Gets the balancing type used by the EPS object, and the
1097:    associated parameters.

1099:    Not Collective

1101:    Input Parameter:
1102: .  eps - the eigensolver context

1104:    Output Parameters:
1105: +  bal    - the balancing method
1106: .  its    - number of iterations of the balancing algorithm
1107: -  cutoff - cutoff value

1109:    Level: intermediate

1111:    Note:
1112:    The user can specify NULL for any parameter that is not needed.

1114: .seealso: EPSSetBalance(), EPSBalance
1115: @*/
1116: PetscErrorCode EPSGetBalance(EPS eps,EPSBalance *bal,PetscInt *its,PetscReal *cutoff)
1117: {
1118:   PetscFunctionBegin;
1120:   if (bal)    *bal = eps->balance;
1121:   if (its)    *its = eps->balance_its;
1122:   if (cutoff) *cutoff = eps->balance_cutoff;
1123:   PetscFunctionReturn(PETSC_SUCCESS);
1124: }

1126: /*@
1127:    EPSSetTwoSided - Sets the solver to use a two-sided variant so that left
1128:    eigenvectors are also computed.

1130:    Logically Collective

1132:    Input Parameters:
1133: +  eps      - the eigensolver context
1134: -  twosided - whether the two-sided variant is to be used or not

1136:    Options Database Keys:
1137: .  -eps_two_sided <boolean> - Sets/resets the twosided flag

1139:    Notes:
1140:    If the user sets twosided=PETSC_TRUE then the solver uses a variant of
1141:    the algorithm that computes both right and left eigenvectors. This is
1142:    usually much more costly. This option is not available in all solvers.

1144:    When using two-sided solvers, the problem matrices must have both the
1145:    MatMult and MatMultTranspose operations defined.

1147:    Level: advanced

1149: .seealso: EPSGetTwoSided(), EPSGetLeftEigenvector()
1150: @*/
1151: PetscErrorCode EPSSetTwoSided(EPS eps,PetscBool twosided)
1152: {
1153:   PetscFunctionBegin;
1156:   if (twosided!=eps->twosided) {
1157:     eps->twosided = twosided;
1158:     eps->state    = EPS_STATE_INITIAL;
1159:   }
1160:   PetscFunctionReturn(PETSC_SUCCESS);
1161: }

1163: /*@
1164:    EPSGetTwoSided - Returns the flag indicating whether a two-sided variant
1165:    of the algorithm is being used or not.

1167:    Not Collective

1169:    Input Parameter:
1170: .  eps - the eigensolver context

1172:    Output Parameter:
1173: .  twosided - the returned flag

1175:    Level: advanced

1177: .seealso: EPSSetTwoSided()
1178: @*/
1179: PetscErrorCode EPSGetTwoSided(EPS eps,PetscBool *twosided)
1180: {
1181:   PetscFunctionBegin;
1183:   PetscAssertPointer(twosided,2);
1184:   *twosided = eps->twosided;
1185:   PetscFunctionReturn(PETSC_SUCCESS);
1186: }

1188: /*@
1189:    EPSSetTrueResidual - Specifies if the solver must compute the true residual
1190:    explicitly or not.

1192:    Logically Collective

1194:    Input Parameters:
1195: +  eps     - the eigensolver context
1196: -  trueres - whether true residuals are required or not

1198:    Options Database Keys:
1199: .  -eps_true_residual <boolean> - Sets/resets the boolean flag 'trueres'

1201:    Notes:
1202:    If the user sets trueres=PETSC_TRUE then the solver explicitly computes
1203:    the true residual for each eigenpair approximation, and uses it for
1204:    convergence testing. Computing the residual is usually an expensive
1205:    operation. Some solvers (e.g., Krylov solvers) can avoid this computation
1206:    by using a cheap estimate of the residual norm, but this may sometimes
1207:    give inaccurate results (especially if a spectral transform is being
1208:    used). On the contrary, preconditioned eigensolvers (e.g., Davidson solvers)
1209:    do rely on computing the true residual, so this option is irrelevant for them.

1211:    Level: advanced

1213: .seealso: EPSGetTrueResidual()
1214: @*/
1215: PetscErrorCode EPSSetTrueResidual(EPS eps,PetscBool trueres)
1216: {
1217:   PetscFunctionBegin;
1220:   eps->trueres = trueres;
1221:   PetscFunctionReturn(PETSC_SUCCESS);
1222: }

1224: /*@
1225:    EPSGetTrueResidual - Returns the flag indicating whether true
1226:    residuals must be computed explicitly or not.

1228:    Not Collective

1230:    Input Parameter:
1231: .  eps - the eigensolver context

1233:    Output Parameter:
1234: .  trueres - the returned flag

1236:    Level: advanced

1238: .seealso: EPSSetTrueResidual()
1239: @*/
1240: PetscErrorCode EPSGetTrueResidual(EPS eps,PetscBool *trueres)
1241: {
1242:   PetscFunctionBegin;
1244:   PetscAssertPointer(trueres,2);
1245:   *trueres = eps->trueres;
1246:   PetscFunctionReturn(PETSC_SUCCESS);
1247: }

1249: /*@
1250:    EPSSetTrackAll - Specifies if the solver must compute the residual norm of all
1251:    approximate eigenpairs or not.

1253:    Logically Collective

1255:    Input Parameters:
1256: +  eps      - the eigensolver context
1257: -  trackall - whether to compute all residuals or not

1259:    Notes:
1260:    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
1261:    the residual norm for each eigenpair approximation. Computing the residual is
1262:    usually an expensive operation and solvers commonly compute only the residual
1263:    associated to the first unconverged eigenpair.

1265:    The option '-eps_monitor_all' automatically activates this option.

1267:    Level: developer

1269: .seealso: EPSGetTrackAll()
1270: @*/
1271: PetscErrorCode EPSSetTrackAll(EPS eps,PetscBool trackall)
1272: {
1273:   PetscFunctionBegin;
1276:   eps->trackall = trackall;
1277:   PetscFunctionReturn(PETSC_SUCCESS);
1278: }

1280: /*@
1281:    EPSGetTrackAll - Returns the flag indicating whether all residual norms must
1282:    be computed or not.

1284:    Not Collective

1286:    Input Parameter:
1287: .  eps - the eigensolver context

1289:    Output Parameter:
1290: .  trackall - the returned flag

1292:    Level: developer

1294: .seealso: EPSSetTrackAll()
1295: @*/
1296: PetscErrorCode EPSGetTrackAll(EPS eps,PetscBool *trackall)
1297: {
1298:   PetscFunctionBegin;
1300:   PetscAssertPointer(trackall,2);
1301:   *trackall = eps->trackall;
1302:   PetscFunctionReturn(PETSC_SUCCESS);
1303: }

1305: /*@
1306:    EPSSetPurify - Deactivate eigenvector purification (which is activated by default).

1308:    Logically Collective

1310:    Input Parameters:
1311: +  eps    - the eigensolver context
1312: -  purify - whether purification is required or not

1314:    Options Database Keys:
1315: .  -eps_purify <boolean> - Sets/resets the boolean flag 'purify'

1317:    Notes:
1318:    By default, eigenvectors of generalized symmetric eigenproblems are purified
1319:    in order to purge directions in the nullspace of matrix B. If the user knows
1320:    that B is non-singular, then purification can be safely deactivated and some
1321:    computational cost is avoided (this is particularly important in interval computations).

1323:    Level: intermediate

1325: .seealso: EPSGetPurify(), EPSSetInterval()
1326: @*/
1327: PetscErrorCode EPSSetPurify(EPS eps,PetscBool purify)
1328: {
1329:   PetscFunctionBegin;
1332:   if (purify!=eps->purify) {
1333:     eps->purify = purify;
1334:     eps->state  = EPS_STATE_INITIAL;
1335:   }
1336:   PetscFunctionReturn(PETSC_SUCCESS);
1337: }

1339: /*@
1340:    EPSGetPurify - Returns the flag indicating whether purification is activated
1341:    or not.

1343:    Not Collective

1345:    Input Parameter:
1346: .  eps - the eigensolver context

1348:    Output Parameter:
1349: .  purify - the returned flag

1351:    Level: intermediate

1353: .seealso: EPSSetPurify()
1354: @*/
1355: PetscErrorCode EPSGetPurify(EPS eps,PetscBool *purify)
1356: {
1357:   PetscFunctionBegin;
1359:   PetscAssertPointer(purify,2);
1360:   *purify = eps->purify;
1361:   PetscFunctionReturn(PETSC_SUCCESS);
1362: }

1364: /*@
1365:    EPSSetOptionsPrefix - Sets the prefix used for searching for all
1366:    EPS options in the database.

1368:    Logically Collective

1370:    Input Parameters:
1371: +  eps - the eigensolver context
1372: -  prefix - the prefix string to prepend to all EPS option requests

1374:    Notes:
1375:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1376:    The first character of all runtime options is AUTOMATICALLY the
1377:    hyphen.

1379:    For example, to distinguish between the runtime options for two
1380:    different EPS contexts, one could call
1381: .vb
1382:       EPSSetOptionsPrefix(eps1,"eig1_")
1383:       EPSSetOptionsPrefix(eps2,"eig2_")
1384: .ve

1386:    Level: advanced

1388: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
1389: @*/
1390: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
1391: {
1392:   PetscFunctionBegin;
1394:   if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
1395:   PetscCall(STSetOptionsPrefix(eps->st,prefix));
1396:   if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
1397:   PetscCall(BVSetOptionsPrefix(eps->V,prefix));
1398:   if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
1399:   PetscCall(DSSetOptionsPrefix(eps->ds,prefix));
1400:   if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
1401:   PetscCall(RGSetOptionsPrefix(eps->rg,prefix));
1402:   PetscCall(PetscObjectSetOptionsPrefix((PetscObject)eps,prefix));
1403:   PetscFunctionReturn(PETSC_SUCCESS);
1404: }

1406: /*@
1407:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all
1408:    EPS options in the database.

1410:    Logically Collective

1412:    Input Parameters:
1413: +  eps - the eigensolver context
1414: -  prefix - the prefix string to prepend to all EPS option requests

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

1420:    Level: advanced

1422: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
1423: @*/
1424: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
1425: {
1426:   PetscFunctionBegin;
1428:   if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
1429:   PetscCall(STAppendOptionsPrefix(eps->st,prefix));
1430:   if (!eps->V) PetscCall(EPSGetBV(eps,&eps->V));
1431:   PetscCall(BVAppendOptionsPrefix(eps->V,prefix));
1432:   if (!eps->ds) PetscCall(EPSGetDS(eps,&eps->ds));
1433:   PetscCall(DSAppendOptionsPrefix(eps->ds,prefix));
1434:   if (!eps->rg) PetscCall(EPSGetRG(eps,&eps->rg));
1435:   PetscCall(RGAppendOptionsPrefix(eps->rg,prefix));
1436:   PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)eps,prefix));
1437:   PetscFunctionReturn(PETSC_SUCCESS);
1438: }

1440: /*@
1441:    EPSGetOptionsPrefix - Gets the prefix used for searching for all
1442:    EPS options in the database.

1444:    Not Collective

1446:    Input Parameters:
1447: .  eps - the eigensolver context

1449:    Output Parameters:
1450: .  prefix - pointer to the prefix string used is returned

1452:    Note:
1453:    On the Fortran side, the user should pass in a string 'prefix' of
1454:    sufficient length to hold the prefix.

1456:    Level: advanced

1458: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
1459: @*/
1460: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
1461: {
1462:   PetscFunctionBegin;
1464:   PetscAssertPointer(prefix,2);
1465:   PetscCall(PetscObjectGetOptionsPrefix((PetscObject)eps,prefix));
1466:   PetscFunctionReturn(PETSC_SUCCESS);
1467: }