Actual source code: opts.c

  1: /*
  2:       EPS 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-2009, Universidad Politecnica de Valencia, Spain

  9:    This file is part of SLEPc.
 10:       
 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 private/epsimpl.h

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

 34:    Collective on EPS

 36:    Input Parameters:
 37: .  eps - the eigensolver context

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

 42:    Level: beginner

 44: .seealso: 
 45: @*/
 46: PetscErrorCode EPSSetFromOptions(EPS eps)
 47: {
 49:   char           type[256],monfilename[PETSC_MAX_PATH_LEN];
 50:   PetscTruth     flg;
 51:   PetscReal      r;
 52:   PetscScalar    s;
 53:   PetscInt       i,j,k;
 54:   PetscViewerASCIIMonitor monviewer;

 58:   PetscOptionsBegin(((PetscObject)eps)->comm,((PetscObject)eps)->prefix,"Eigenproblem Solver (EPS) Options","EPS");
 59:     PetscOptionsList("-eps_type","Eigenproblem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);
 60:     if (flg) {
 61:       EPSSetType(eps,type);
 62:     }

 64:     PetscOptionsTruthGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);
 65:     if (flg) {EPSSetProblemType(eps,EPS_HEP);}
 66:     PetscOptionsTruthGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);
 67:     if (flg) {EPSSetProblemType(eps,EPS_GHEP);}
 68:     PetscOptionsTruthGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
 69:     if (flg) {EPSSetProblemType(eps,EPS_NHEP);}
 70:     PetscOptionsTruthGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);
 71:     if (flg) {EPSSetProblemType(eps,EPS_GNHEP);}
 72:     PetscOptionsTruthGroupEnd("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);
 73:     if (flg) {EPSSetProblemType(eps,EPS_PGNHEP);}

 75:     /*
 76:       Set the type if it was never set.
 77:     */
 78:     if (!((PetscObject)eps)->type_name) {
 79:       EPSSetType(eps,EPSKRYLOVSCHUR);
 80:     }

 82:     PetscOptionsTruthGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);
 83:     if (flg) {EPSSetExtraction(eps,EPS_RITZ);}
 84:     PetscOptionsTruthGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);
 85:     if (flg) {EPSSetExtraction(eps,EPS_HARMONIC);}
 86:     PetscOptionsTruthGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);
 87:     if (flg) {EPSSetExtraction(eps,EPS_REFINED);}
 88:     PetscOptionsTruthGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);
 89:     if (flg) {EPSSetExtraction(eps,EPS_REFINED_HARMONIC);}

 91:     PetscOptionsTruthGroupBegin("-eps_oneside","one-sided eigensolver","EPSSetClass",&flg);
 92:     if (flg) {EPSSetClass(eps,EPS_ONE_SIDE);}
 93:     PetscOptionsTruthGroupEnd("-eps_twoside","two-sided eigensolver","EPSSetClass",&flg);
 94:     if (flg) {EPSSetClass(eps,EPS_TWO_SIDE);}

 96:     r = i = PETSC_IGNORE;
 97:     PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,PETSC_NULL);
 98:     PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol,&r,PETSC_NULL);
 99:     EPSSetTolerances(eps,r,i);

101:     i = j = k = PETSC_IGNORE;
102:     PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,PETSC_NULL);
103:     PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,PETSC_NULL);
104:     PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,PETSC_NULL);
105:     EPSSetDimensions(eps,i,j,k);
106: 
107:     /* -----------------------------------------------------------------------*/
108:     /*
109:       Cancels all monitors hardwired into code before call to EPSSetFromOptions()
110:     */
111:     PetscOptionsName("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",&flg);
112:     if (flg) {
113:       EPSMonitorCancel(eps);
114:     }
115:     /*
116:       Prints approximate eigenvalues and error estimates at each iteration
117:     */
118:     PetscOptionsString("-eps_monitor","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
119:     if (flg) {
120:       PetscViewerASCIIMonitorCreate(((PetscObject)eps)->comm,monfilename,((PetscObject)eps)->tablevel,&monviewer);
121:       EPSMonitorSet(eps,EPSMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerASCIIMonitorDestroy);
122:     }
123:     PetscOptionsName("-eps_monitor_draw","Monitor error estimates graphically","EPSMonitorSet",&flg);
124:     if (flg) {
125:       EPSMonitorSet(eps,EPSMonitorLG,PETSC_NULL,PETSC_NULL);
126:     }
127:   /* -----------------------------------------------------------------------*/
128:     PetscOptionsTruthGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
129:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE);}
130:     PetscOptionsTruthGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);
131:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE);}
132:     PetscOptionsTruthGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);
133:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL);}
134:     PetscOptionsTruthGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);
135:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL);}
136:     PetscOptionsTruthGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);
137:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY);}
138:     PetscOptionsTruthGroupEnd("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);
139:     if (flg) {EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY);}

141:     PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);
142:     if (flg) {EPSSetTarget(eps,s);}

144:     PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",0);
145:     PetscOptionsName("-eps_view_binary","Save the matrices associated to the eigenproblem","EPSSetFromOptions",0);
146:     PetscOptionsName("-eps_plot_eigs","Make a plot of the computed eigenvalues","EPSSolve",0);
147: 
148:     if (eps->ops->setfromoptions) {
149:       (*eps->ops->setfromoptions)(eps);
150:     }
151:   PetscOptionsEnd();

153:   IPSetFromOptions(eps->ip);
154:   STSetFromOptions(eps->OP);
155:   return(0);
156: }

160: /*@
161:    EPSGetTolerances - Gets the tolerance and maximum
162:    iteration count used by the default EPS convergence tests. 

164:    Not Collective

166:    Input Parameter:
167: .  eps - the eigensolver context
168:   
169:    Output Parameters:
170: +  tol - the convergence tolerance
171: -  maxits - maximum number of iterations

173:    Notes:
174:    The user can specify PETSC_NULL for any parameter that is not needed.

176:    Level: intermediate

178: .seealso: EPSSetTolerances()
179: @*/
180: PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)
181: {
184:   if (tol)    *tol    = eps->tol;
185:   if (maxits) *maxits = eps->max_it;
186:   return(0);
187: }

191: /*@
192:    EPSSetTolerances - Sets the tolerance and maximum
193:    iteration count used by the default EPS convergence testers. 

195:    Collective on EPS

197:    Input Parameters:
198: +  eps - the eigensolver context
199: .  tol - the convergence tolerance
200: -  maxits - maximum number of iterations to use

202:    Options Database Keys:
203: +  -eps_tol <tol> - Sets the convergence tolerance
204: -  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

206:    Notes:
207:    Use PETSC_IGNORE for an argument that need not be changed.

209:    Use PETSC_DECIDE for maxits to assign a reasonably good value, which is 
210:    dependent on the solution method.

212:    Level: intermediate

214: .seealso: EPSGetTolerances()
215: @*/
216: PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)
217: {
220:   if (tol != PETSC_IGNORE) {
221:     if (tol == PETSC_DEFAULT) {
222:       eps->tol = 1e-7;
223:     } else {
224:       if (tol < 0.0) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
225:       eps->tol = tol;
226:     }
227:   }
228:   if (maxits != PETSC_IGNORE) {
229:     if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
230:       eps->max_it = 0;
231:     } else {
232:       if (maxits < 0) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
233:       eps->max_it = maxits;
234:     }
235:   }
236:   return(0);
237: }

241: /*@
242:    EPSGetDimensions - Gets the number of eigenvalues to compute
243:    and the dimension of the subspace.

245:    Not Collective

247:    Input Parameter:
248: .  eps - the eigensolver context
249:   
250:    Output Parameters:
251: +  nev - number of eigenvalues to compute
252: .  ncv - the maximum dimension of the subspace to be used by the solver
253: -  mpd - the maximum dimension allowed for the projected problem

255:    Notes:
256:    The user can specify PETSC_NULL for any parameter that is not needed.

258:    Level: intermediate

260: .seealso: EPSSetDimensions()
261: @*/
262: PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
263: {
266:   if (nev) *nev = eps->nev;
267:   if (ncv) *ncv = eps->ncv;
268:   if (mpd) *mpd = eps->mpd;
269:   return(0);
270: }

274: /*@
275:    EPSSetDimensions - Sets the number of eigenvalues to compute
276:    and the dimension of the subspace.

278:    Collective on EPS

280:    Input Parameters:
281: +  eps - the eigensolver context
282: .  nev - number of eigenvalues to compute
283: .  ncv - the maximum dimension of the subspace to be used by the solver
284: -  mpd - the maximum dimension allowed for the projected problem

286:    Options Database Keys:
287: +  -eps_nev <nev> - Sets the number of eigenvalues
288: .  -eps_ncv <ncv> - Sets the dimension of the subspace
289: -  -eps_mpd <mpd> - Sets the maximum projected dimension

291:    Notes:
292:    Use PETSC_IGNORE to retain the previous value of any parameter.

294:    Use PETSC_DECIDE for ncv and mpd to assign a reasonably good value, which is
295:    dependent on the solution method.

297:    The parameters ncv and mpd are intimately related, so that the user is advised
298:    to set one of them at most. Normal usage is the following:
299: +  - In cases where nev is small, the user sets ncv (a reasonable default is 2*nev).
300: -  - In cases where nev is large, the user sets mpd.

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

306:    Level: intermediate

308: .seealso: EPSGetDimensions()
309: @*/
310: PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)
311: {

315:   if( nev != PETSC_IGNORE ) {
316:     if (nev<1) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
317:     eps->nev = nev;
318:     eps->setupcalled = 0;
319:   }
320:   if( ncv != PETSC_IGNORE ) {
321:     if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
322:       eps->ncv = 0;
323:     } else {
324:       if (ncv<1) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
325:       eps->ncv = ncv;
326:     }
327:     eps->setupcalled = 0;
328:   }
329:   if( mpd != PETSC_IGNORE ) {
330:     if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
331:       eps->mpd = 0;
332:     } else {
333:       if (mpd<1) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
334:       eps->mpd = mpd;
335:     }
336:   }
337:   return(0);
338: }

342: /*@
343:     EPSSetWhichEigenpairs - Specifies which portion of the spectrum is 
344:     to be sought.

346:     Collective on EPS

348:     Input Parameter:
349: .   eps - eigensolver context obtained from EPSCreate()

351:     Output Parameter:
352: .   which - the portion of the spectrum to be sought

354:     Possible values:
355:     The parameter 'which' can have one of these values:
356:     
357: +     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
358: .     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
359: .     EPS_LARGEST_REAL - largest real parts
360: .     EPS_SMALLEST_REAL - smallest real parts
361: .     EPS_LARGEST_IMAGINARY - largest imaginary parts
362: -     EPS_SMALLEST_IMAGINARY - smallest imaginary parts

364:     Options Database Keys:
365: +   -eps_largest_magnitude - Sets largest eigenvalues in magnitude
366: .   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude
367: .   -eps_largest_real - Sets largest real parts
368: .   -eps_smallest_real - Sets smallest real parts
369: .   -eps_largest_imaginary - Sets largest imaginary parts in magnitude
370: -   -eps_smallest_imaginary - Sets smallest imaginary parts in magnitude

372:     Notes:
373:     Not all eigensolvers implemented in EPS account for all the possible values
374:     stated above. Also, some values make sense only for certain types of 
375:     problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY
376:     and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part 
377:     for eigenvalue selection.     
378:     
379:     Level: intermediate

381: .seealso: EPSGetWhichEigenpairs(), EPSSortEigenvalues(), EPSWhich
382: @*/
383: PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)
384: {
387:   switch (which) {
388:     case EPS_LARGEST_MAGNITUDE:
389:     case EPS_SMALLEST_MAGNITUDE:
390:     case EPS_LARGEST_REAL:
391:     case EPS_SMALLEST_REAL:
392:     case EPS_LARGEST_IMAGINARY:
393:     case EPS_SMALLEST_IMAGINARY:
394:       if (eps->which != which) {
395:         eps->setupcalled = 0;
396:         eps->which = which;
397:       }
398:       break;
399:     default:
400:       SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
401:   }
402:   return(0);
403: }

407: /*@C
408:     EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be 
409:     sought.

411:     Not Collective

413:     Input Parameter:
414: .   eps - eigensolver context obtained from EPSCreate()

416:     Output Parameter:
417: .   which - the portion of the spectrum to be sought

419:     Notes:
420:     See EPSSetWhichEigenpairs() for possible values of which

422:     Level: intermediate

424: .seealso: EPSSetWhichEigenpairs(), EPSWhich
425: @*/
426: PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)
427: {
431:   *which = eps->which;
432:   return(0);
433: }

437: /*@
438:    EPSSetProblemType - Specifies the type of the eigenvalue problem.

440:    Collective on EPS

442:    Input Parameters:
443: +  eps      - the eigensolver context
444: -  type     - a known type of eigenvalue problem 

446:    Options Database Keys:
447: +  -eps_hermitian - Hermitian eigenvalue problem
448: .  -eps_gen_hermitian - generalized Hermitian eigenvalue problem
449: .  -eps_non_hermitian - non-Hermitian eigenvalue problem
450: .  -eps_gen_non_hermitian - generalized non-Hermitian eigenvalue problem 
451: -  -eps_pos_gen_non_hermitian - generalized non-Hermitian eigenvalue problem 
452:    with positive semi-definite B
453:     
454:    Notes:  
455:    Allowed values for the problem type are: Hermitian (EPS_HEP), non-Hermitian
456:    (EPS_NHEP), generalized Hermitian (EPS_GHEP) and generalized non-Hermitian 
457:    (EPS_GNHEP).

459:    This function must be used to instruct SLEPc to exploit symmetry. If no
460:    problem type is specified, by default a non-Hermitian problem is assumed
461:    (either standard or generalized). If the user knows that the problem is
462:    Hermitian (i.e. A=A^H) of generalized Hermitian (i.e. A=A^H, B=B^H, and 
463:    B positive definite) then it is recommended to set the problem type so
464:    that eigensolver can exploit these properties. 

466:    Level: beginner

468: .seealso: EPSSetOperators(), EPSSetType(), EPSGetProblemType(), EPSProblemType
469: @*/
470: PetscErrorCode EPSSetProblemType(EPS eps,EPSProblemType type)
471: {

475:   switch (type) {
476:     case EPS_HEP:
477:       eps->isgeneralized = PETSC_FALSE;
478:       eps->ishermitian = PETSC_TRUE;
479:       eps->ispositive = PETSC_FALSE;
480:       break;
481:     case EPS_NHEP:
482:       eps->isgeneralized = PETSC_FALSE;
483:       eps->ishermitian = PETSC_FALSE;
484:       eps->ispositive = PETSC_FALSE;
485:       break;
486:     case EPS_GHEP:
487:       eps->isgeneralized = PETSC_TRUE;
488:       eps->ishermitian = PETSC_TRUE;
489:       eps->ispositive = PETSC_TRUE;
490:       break;
491:     case EPS_GNHEP:
492:       eps->isgeneralized = PETSC_TRUE;
493:       eps->ishermitian = PETSC_FALSE;
494:       eps->ispositive = PETSC_FALSE;
495:       break;
496:     case EPS_PGNHEP:
497:       eps->isgeneralized = PETSC_TRUE;
498:       eps->ishermitian = PETSC_FALSE;
499:       eps->ispositive = PETSC_TRUE;
500:       break;
501: /*
502:     case EPS_CSEP: 
503:       eps->isgeneralized = PETSC_FALSE;
504:       eps->ishermitian = PETSC_FALSE;
505:       STSetBilinearForm(eps->OP,STINNER_SYMMETRIC);
506:       break;
507:     case EPS_GCSEP:
508:       eps->isgeneralized = PETSC_TRUE;
509:       eps->ishermitian = PETSC_FALSE;
510:       STSetBilinearForm(eps->OP,STINNER_B_SYMMETRIC);
511:       break;
512: */
513:     default:
514:       SETERRQ(PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
515:   }
516:   eps->problem_type = type;

518:   return(0);
519: }

523: /*@C
524:    EPSGetProblemType - Gets the problem type from the EPS object.

526:    Not Collective

528:    Input Parameter:
529: .  eps - the eigensolver context 

531:    Output Parameter:
532: .  type - name of EPS problem type 

534:    Level: intermediate

536: .seealso: EPSSetProblemType(), EPSProblemType
537: @*/
538: PetscErrorCode EPSGetProblemType(EPS eps,EPSProblemType *type)
539: {
543:   *type = eps->problem_type;
544:   return(0);
545: }

549: /*@
550:    EPSSetExtraction - Specifies the type of extraction technique to be employed 
551:    by the eigensolver.

553:    Collective on EPS

555:    Input Parameters:
556: +  eps  - the eigensolver context
557: -  extr - a known type of extraction

559:    Options Database Keys:
560: +  -eps_ritz - Rayleigh-Ritz extraction
561: .  -eps_harmonic - hamonic Ritz extraction
562: .  -eps_refined - refined Ritz extraction
563: -  -eps_refined_harmonic - refined harmonic Ritz extraction
564:     
565:    Notes:  
566:    Not all eigensolvers support all types of extraction. See the SLEPc
567:    Users Manual for details.

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

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

574:    Level: beginner

576: .seealso: EPSSetTarget(), EPSGetExtraction(), EPSExtraction
577: @*/
578: PetscErrorCode EPSSetExtraction(EPS eps,EPSExtraction extr)
579: {
582:   eps->extraction = extr;
583:   return(0);
584: }

588: /*@C
589:    EPSGetExtraction - Gets the extraction type used by the EPS object.

591:    Not Collective

593:    Input Parameter:
594: .  eps - the eigensolver context 

596:    Output Parameter:
597: .  extr - name of extraction type 

599:    Level: intermediate

601: .seealso: EPSSetExtraction(), EPSExtraction
602: @*/
603: PetscErrorCode EPSGetExtraction(EPS eps,EPSExtraction *extr)
604: {
608:   *extr = eps->extraction;
609:   return(0);
610: }

614: /*@
615:    EPSSetClass - Specifies the eigensolver class: either one-sided or two-sided.

617:    Collective on EPS

619:    Input Parameters:
620: +  eps      - the eigensolver context
621: -  class    - the class of solver

623:    Options Database Keys:
624: +  -eps_oneside - one-sided solver
625: -  -eps_twoside - two-sided solver
626:     
627:    Note:  
628:    Allowed solver classes are: one-sided (EPS_ONE_SIDE) and two-sided (EPS_TWO_SIDE).
629:    One-sided eigensolvers are the standard ones, which allow the computation of
630:    eigenvalues and (right) eigenvectors, whereas two-sided eigensolvers compute
631:    left eigenvectors as well.

633:    Level: intermediate

635: .seealso: EPSGetLeftVector(), EPSComputeRelativeErrorLeft(), EPSSetLeftInitialVector(),
636:    EPSGetClass(), EPSClass
637: @*/
638: PetscErrorCode EPSSetClass(EPS eps,EPSClass cl)
639: {


645:   if (cl != EPS_ONE_SIDE && cl != EPS_TWO_SIDE) SETERRQ(PETSC_ERR_ARG_WRONG,"Unknown eigensolver class");
646:   if (eps->solverclass!=cl) {
647:     if (eps->solverclass == EPS_TWO_SIDE) { EPSFreeSolution(eps); }
648:     eps->solverclass = cl;
649:   }

651:   return(0);
652: }

656: /*@C
657:    EPSGetClass - Gets the eigensolver class from the EPS object.

659:    Not Collective

661:    Input Parameter:
662: .  eps - the eigensolver context 

664:    Output Parameter:
665: .  class - class of EPS solver (either one-sided or two-sided)

667:    Level: intermediate

669: .seealso: EPSSetClass(), EPSClass
670: @*/
671: PetscErrorCode EPSGetClass(EPS eps,EPSClass *cl)
672: {
676:   *cl = eps->solverclass;
677:   return(0);
678: }

682: /*@C
683:    EPSSetOptionsPrefix - Sets the prefix used for searching for all 
684:    EPS options in the database.

686:    Collective on EPS

688:    Input Parameters:
689: +  eps - the eigensolver context
690: -  prefix - the prefix string to prepend to all EPS option requests

692:    Notes:
693:    A hyphen (-) must NOT be given at the beginning of the prefix name.
694:    The first character of all runtime options is AUTOMATICALLY the
695:    hyphen.

697:    For example, to distinguish between the runtime options for two
698:    different EPS contexts, one could call
699: .vb
700:       EPSSetOptionsPrefix(eps1,"eig1_")
701:       EPSSetOptionsPrefix(eps2,"eig2_")
702: .ve

704:    Level: advanced

706: .seealso: EPSAppendOptionsPrefix(), EPSGetOptionsPrefix()
707: @*/
708: PetscErrorCode EPSSetOptionsPrefix(EPS eps,const char *prefix)
709: {
713:   PetscObjectSetOptionsPrefix((PetscObject)eps, prefix);
714:   STSetOptionsPrefix(eps->OP,prefix);
715:   IPSetOptionsPrefix(eps->ip,prefix);
716:   IPAppendOptionsPrefix(eps->ip,"eps_");
717:   return(0);
718: }
719: 
722: /*@C
723:    EPSAppendOptionsPrefix - Appends to the prefix used for searching for all 
724:    EPS options in the database.

726:    Collective on EPS

728:    Input Parameters:
729: +  eps - the eigensolver context
730: -  prefix - the prefix string to prepend to all EPS option requests

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

736:    Level: advanced

738: .seealso: EPSSetOptionsPrefix(), EPSGetOptionsPrefix()
739: @*/
740: PetscErrorCode EPSAppendOptionsPrefix(EPS eps,const char *prefix)
741: {
745:   PetscObjectAppendOptionsPrefix((PetscObject)eps, prefix);
746:   STAppendOptionsPrefix(eps->OP,prefix);
747:   IPSetOptionsPrefix(eps->ip,prefix);
748:   IPAppendOptionsPrefix(eps->ip,"eps_");
749:   return(0);
750: }

754: /*@C
755:    EPSGetOptionsPrefix - Gets the prefix used for searching for all 
756:    EPS options in the database.

758:    Not Collective

760:    Input Parameters:
761: .  eps - the eigensolver context

763:    Output Parameters:
764: .  prefix - pointer to the prefix string used is returned

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

769:    Level: advanced

771: .seealso: EPSSetOptionsPrefix(), EPSAppendOptionsPrefix()
772: @*/
773: PetscErrorCode EPSGetOptionsPrefix(EPS eps,const char *prefix[])
774: {
779:   PetscObjectGetOptionsPrefix((PetscObject)eps, prefix);
780:   return(0);
781: }