Actual source code: basic.c

  1: /*
  2:      The basic EPS routines, Create, View, etc. are here.

  4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  6:    Copyright (c) 2002-2010, Universidad Politecnica de Valencia, Spain

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

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

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

 24:  #include private/epsimpl.h

 26: PetscFList EPSList = 0;
 27: PetscCookie EPS_COOKIE = 0;
 28: PetscLogEvent EPS_SetUp = 0, EPS_Solve = 0, EPS_Dense = 0;
 29: static PetscTruth EPSPackageInitialized = PETSC_FALSE;

 33: /*@C
 34:   EPSFinalizePackage - This function destroys everything in the Slepc interface to the EPS package. It is
 35:   called from SlepcFinalize().

 37:   Level: developer

 39: .seealso: SlepcFinalize()
 40: @*/
 41: PetscErrorCode EPSFinalizePackage(void)
 42: {
 44:   EPSPackageInitialized = PETSC_FALSE;
 45:   EPSList               = 0;
 46:   return(0);
 47: }

 51: /*@C
 52:   EPSInitializePackage - This function initializes everything in the EPS package. It is called
 53:   from PetscDLLibraryRegister() when using dynamic libraries, and on the first call to EPSCreate()
 54:   when using static libraries.

 56:   Input Parameter:
 57:   path - The dynamic library path, or PETSC_NULL

 59:   Level: developer

 61: .seealso: SlepcInitialize()
 62: @*/
 63: PetscErrorCode EPSInitializePackage(char *path) {
 64:   char              logList[256];
 65:   char             *className;
 66:   PetscTruth        opt;

 70:   if (EPSPackageInitialized) return(0);
 71:   EPSPackageInitialized = PETSC_TRUE;
 72:   /* Register Classes */
 73:   PetscCookieRegister("Eigenproblem Solver",&EPS_COOKIE);
 74:   /* Register Constructors */
 75:   EPSRegisterAll(path);
 76:   /* Register Events */
 77:   PetscLogEventRegister("EPSSetUp",EPS_COOKIE,&EPS_SetUp);
 78:   PetscLogEventRegister("EPSSolve",EPS_COOKIE,&EPS_Solve);
 79:   PetscLogEventRegister("EPSDense",EPS_COOKIE,&EPS_Dense);
 80:   /* Process info exclusions */
 81:   PetscOptionsGetString(PETSC_NULL, "-log_info_exclude", logList, 256, &opt);
 82:   if (opt) {
 83:     PetscStrstr(logList, "eps", &className);
 84:     if (className) {
 85:       PetscInfoDeactivateClass(EPS_COOKIE);
 86:     }
 87:   }
 88:   /* Process summary exclusions */
 89:   PetscOptionsGetString(PETSC_NULL, "-log_summary_exclude", logList, 256, &opt);
 90:   if (opt) {
 91:     PetscStrstr(logList, "eps", &className);
 92:     if (className) {
 93:       PetscLogEventDeactivateClass(EPS_COOKIE);
 94:     }
 95:   }
 96:   PetscRegisterFinalize(EPSFinalizePackage);
 97:   return(0);
 98: }

102: /*@C
103:    EPSView - Prints the EPS data structure.

105:    Collective on EPS

107:    Input Parameters:
108: +  eps - the eigenproblem solver context
109: -  viewer - optional visualization context

111:    Options Database Key:
112: .  -eps_view -  Calls EPSView() at end of EPSSolve()

114:    Note:
115:    The available visualization contexts include
116: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
117: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
118:          output where only the first processor opens
119:          the file.  All other processors send their 
120:          data to the first processor to print. 

122:    The user can open an alternative visualization context with
123:    PetscViewerASCIIOpen() - output to a specified file.

125:    Level: beginner

127: .seealso: STView(), PetscViewerASCIIOpen()
128: @*/
129: PetscErrorCode EPSView(EPS eps,PetscViewer viewer)
130: {
132:   const char     *type,*extr,*bal;
133:   PetscTruth     isascii;

137:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(((PetscObject)eps)->comm);

141: #if defined(PETSC_USE_COMPLEX)
142: #define HERM "hermitian"
143: #else
144: #define HERM "symmetric"
145: #endif
146:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);
147:   if (isascii) {
148:     PetscViewerASCIIPrintf(viewer,"EPS Object:\n");
149:     switch (eps->problem_type) {
150:       case EPS_HEP:   type = HERM " eigenvalue problem"; break;
151:       case EPS_GHEP:  type = "generalized " HERM " eigenvalue problem"; break;
152:       case EPS_NHEP:  type = "non-" HERM " eigenvalue problem"; break;
153:       case EPS_GNHEP: type = "generalized non-" HERM " eigenvalue problem"; break;
154:       case EPS_PGNHEP: type = "generalized non-" HERM " eigenvalue problem with " HERM " positive definite B"; break;
155:       case 0:         type = "not yet set"; break;
156:       default: SETERRQ(1,"Wrong value of eps->problem_type");
157:     }
158:     PetscViewerASCIIPrintf(viewer,"  problem type: %s\n",type);
159:     EPSGetType(eps,&type);
160:     if (type) {
161:       PetscViewerASCIIPrintf(viewer,"  method: %s\n",type);
162:     } else {
163:       PetscViewerASCIIPrintf(viewer,"  method: not yet set\n");
164:     }
165:     if (eps->ops->view) {
166:       PetscViewerASCIIPushTab(viewer);
167:       (*eps->ops->view)(eps,viewer);
168:       PetscViewerASCIIPopTab(viewer);
169:     }
170:     if (eps->extraction) {
171:       switch (eps->extraction) {
172:         case EPS_RITZ:             extr = "Rayleigh-Ritz"; break;
173:         case EPS_HARMONIC:         extr = "harmonic Ritz"; break;
174:         case EPS_HARMONIC_RELATIVE:extr = "relative harmonic Ritz"; break;
175:         case EPS_HARMONIC_RIGHT:   extr = "right harmonic Ritz"; break;
176:         case EPS_HARMONIC_LARGEST: extr = "largest harmonic Ritz"; break;
177:         case EPS_REFINED:          extr = "refined Ritz"; break;
178:         case EPS_REFINED_HARMONIC: extr = "refined harmonic Ritz"; break;
179:         default: SETERRQ(1,"Wrong value of eps->extraction");
180:       }
181:       PetscViewerASCIIPrintf(viewer,"  extraction type: %s\n",extr);
182:     }
183:     if (eps->balance && !eps->ishermitian && eps->balance!=EPS_BALANCE_NONE) {
184:       switch (eps->balance) {
185:         case EPS_BALANCE_ONESIDE:   bal = "one-sided Krylov"; break;
186:         case EPS_BALANCE_TWOSIDE:   bal = "two-sided Krylov"; break;
187:         case EPS_BALANCE_USER:      bal = "user-defined matrix"; break;
188:         default: SETERRQ(1,"Wrong value of eps->balance");
189:       }
190:       PetscViewerASCIIPrintf(viewer,"  balancing enabled: %s",bal);
191:       if (eps->balance==EPS_BALANCE_ONESIDE || eps->balance==EPS_BALANCE_TWOSIDE) {
192:         PetscViewerASCIIPrintf(viewer,", with its=%d",eps->balance_its);
193:       }
194:       if (eps->balance==EPS_BALANCE_TWOSIDE && eps->balance_cutoff!=0.0) {
195:         PetscViewerASCIIPrintf(viewer," and cutoff=%g",eps->balance_cutoff);
196:       }
197:       PetscViewerASCIIPrintf(viewer,"\n");
198:     }
199:     PetscViewerASCIIPrintf(viewer,"  selected portion of the spectrum: ");
200:     if (!eps->which) {
201:       PetscViewerASCIIPrintf(viewer,"not yet set\n");
202:     } else switch (eps->which) {
203:       case EPS_WHICH_USER:
204:         PetscViewerASCIIPrintf(viewer,"user defined\n");
205:         break;
206:       case EPS_TARGET_MAGNITUDE:
207: #if !defined(PETSC_USE_COMPLEX)
208:         PetscViewerASCIIPrintf(viewer,"closest to target: %g (in magnitude)\n",eps->target);
209: #else
210:         PetscViewerASCIIPrintf(viewer,"closest to target: %g+%g i (in magnitude)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
211: #endif
212:         break;
213:       case EPS_TARGET_REAL:
214: #if !defined(PETSC_USE_COMPLEX)
215:         PetscViewerASCIIPrintf(viewer,"closest to target: %g (along the real axis)\n",eps->target);
216: #else
217:         PetscViewerASCIIPrintf(viewer,"closest to target: %g+%g i (along the real axis)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
218: #endif
219:         break;
220: #if defined(PETSC_USE_COMPLEX)
221:       case EPS_TARGET_IMAGINARY:
222:         PetscViewerASCIIPrintf(viewer,"closest to target: %g+%g i (along the imaginary axis)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
223:         break;
224: #endif
225:       case EPS_LARGEST_MAGNITUDE:
226:         PetscViewerASCIIPrintf(viewer,"largest eigenvalues in magnitude\n");
227:         break;
228:       case EPS_SMALLEST_MAGNITUDE:
229:         PetscViewerASCIIPrintf(viewer,"smallest eigenvalues in magnitude\n");
230:         break;
231:       case EPS_LARGEST_REAL:
232:         PetscViewerASCIIPrintf(viewer,"largest real parts\n");
233:         break;
234:       case EPS_SMALLEST_REAL:
235:         PetscViewerASCIIPrintf(viewer,"smallest real parts\n");
236:         break;
237:       case EPS_LARGEST_IMAGINARY:
238:         PetscViewerASCIIPrintf(viewer,"largest imaginary parts\n");
239:         break;
240:       case EPS_SMALLEST_IMAGINARY:
241:         PetscViewerASCIIPrintf(viewer,"smallest imaginary parts\n");
242:         break;
243:       default: SETERRQ(1,"Wrong value of eps->which");
244:     }
245:     if (eps->leftvecs) {
246:       PetscViewerASCIIPrintf(viewer,"  computing left eigenvectors also\n");
247:     }
248:     if (eps->trueres) {
249:       PetscViewerASCIIPrintf(viewer,"  computing true residuals explicitly\n");
250:     }
251:     if (eps->trackall) {
252:       PetscViewerASCIIPrintf(viewer,"  computing all residuals (for tracking convergence)\n");
253:     }
254:     PetscViewerASCIIPrintf(viewer,"  number of eigenvalues (nev): %d\n",eps->nev);
255:     PetscViewerASCIIPrintf(viewer,"  number of column vectors (ncv): %d\n",eps->ncv);
256:     PetscViewerASCIIPrintf(viewer,"  maximum dimension of projected problem (mpd): %d\n",eps->mpd);
257:     PetscViewerASCIIPrintf(viewer,"  maximum number of iterations: %d\n", eps->max_it);
258:     PetscViewerASCIIPrintf(viewer,"  tolerance: %g\n",eps->tol);
259:     switch(eps->conv) {
260:     case EPS_CONV_ABS:
261:       PetscViewerASCIIPrintf(viewer,"  absolute error convergence test\n");break;
262:     case EPS_CONV_EIG:
263:       PetscViewerASCIIPrintf(viewer,"  eigenvalue relative error convergence test\n");break;
264:     case EPS_CONV_NORM:
265:       PetscViewerASCIIPrintf(viewer,"  eigenvalue and matrix norm relative error convergence test\n");break;
266:     default:
267:       PetscViewerASCIIPrintf(viewer,"  user defined convergence test\n");break;
268:     }
269:     if (eps->nini!=0) {
270:       PetscViewerASCIIPrintf(viewer,"  dimension of user-provided initial space: %d\n",PetscAbs(eps->nini));
271:     }
272:     if (eps->ninil!=0) {
273:       PetscViewerASCIIPrintf(viewer,"  dimension of user-provided initial left space: %d\n",PetscAbs(eps->ninil));
274:     }
275:     if (eps->nds>0) {
276:       PetscViewerASCIIPrintf(viewer,"  dimension of user-provided deflation space: %d\n",eps->nds);
277:     }
278:     PetscViewerASCIIPrintf(viewer,"  estimates of matrix norms (%s): norm(A)=%g",eps->adaptive?"adaptive":"constant",eps->nrma);
279:     if (eps->isgeneralized) {
280:       PetscViewerASCIIPrintf(viewer,", norm(B)=%g",eps->nrmb);
281:     }
282:     PetscViewerASCIIPrintf(viewer,"\n");
283:     PetscViewerASCIIPushTab(viewer);
284:     IPView(eps->ip,viewer);
285:     STView(eps->OP,viewer);
286:     PetscViewerASCIIPopTab(viewer);
287:   } else {
288:     if (eps->ops->view) {
289:       (*eps->ops->view)(eps,viewer);
290:     }
291:     STView(eps->OP,viewer);
292:   }
293:   return(0);
294: }

298: /*@C
299:    EPSCreate - Creates the default EPS context.

301:    Collective on MPI_Comm

303:    Input Parameter:
304: .  comm - MPI communicator

306:    Output Parameter:
307: .  eps - location to put the EPS context

309:    Note:
310:    The default EPS type is EPSKRYLOVSCHUR

312:    Level: beginner

314: .seealso: EPSSetUp(), EPSSolve(), EPSDestroy(), EPS
315: @*/
316: PetscErrorCode EPSCreate(MPI_Comm comm,EPS *outeps)
317: {
319:   EPS            eps;

323:   *outeps = 0;

325:   PetscHeaderCreate(eps,_p_EPS,struct _EPSOps,EPS_COOKIE,-1,"EPS",comm,EPSDestroy,EPSView);
326:   *outeps = eps;

328:   PetscMemzero(eps->ops,sizeof(struct _EPSOps));

330:   eps->max_it          = 0;
331:   eps->nev             = 1;
332:   eps->ncv             = 0;
333:   eps->mpd             = 0;
334:   eps->allocated_ncv   = 0;
335:   eps->nini            = 0;
336:   eps->ninil           = 0;
337:   eps->nds             = 0;
338:   eps->tol             = 1e-7;
339:   eps->conv_func       = EPSEigRelativeConverged;
340:   eps->conv_ctx        = PETSC_NULL;
341:   eps->which           = (EPSWhich)0;
342:   eps->which_func      = PETSC_NULL;
343:   eps->which_ctx       = PETSC_NULL;
344:   eps->leftvecs        = PETSC_FALSE;
345:   eps->trueres         = PETSC_FALSE;
346:   eps->trackall        = PETSC_FALSE;
347:   eps->target          = 0.0;
348:   eps->evecsavailable  = PETSC_FALSE;
349:   eps->problem_type    = (EPSProblemType)0;
350:   eps->extraction      = (EPSExtraction)0;
351:   eps->balance         = (EPSBalance)0;
352:   eps->balance_its     = 5;
353:   eps->balance_cutoff  = 1e-8;
354:   eps->nrma            = 1.0;
355:   eps->nrmb            = 1.0;
356:   eps->adaptive        = PETSC_FALSE;

358:   eps->V               = 0;
359:   eps->W               = 0;
360:   eps->T               = 0;
361:   eps->DS              = 0;
362:   eps->IS              = 0;
363:   eps->ISL             = 0;
364:   eps->ds_ortho        = PETSC_FALSE;
365:   eps->eigr            = 0;
366:   eps->eigi            = 0;
367:   eps->errest          = 0;
368:   eps->errest_left     = 0;
369:   eps->OP              = 0;
370:   eps->ip              = 0;
371:   eps->data            = 0;
372:   eps->nconv           = 0;
373:   eps->its             = 0;
374:   eps->perm            = PETSC_NULL;

376:   eps->nwork           = 0;
377:   eps->work            = 0;
378:   eps->isgeneralized   = PETSC_FALSE;
379:   eps->ishermitian     = PETSC_FALSE;
380:   eps->ispositive      = PETSC_FALSE;
381:   eps->setupcalled     = 0;
382:   eps->reason          = EPS_CONVERGED_ITERATING;

384:   eps->numbermonitors  = 0;

386:   STCreate(comm,&eps->OP);
387:   PetscLogObjectParent(eps,eps->OP);
388:   IPCreate(comm,&eps->ip);
389:   IPSetOptionsPrefix(eps->ip,((PetscObject)eps)->prefix);
390:   IPAppendOptionsPrefix(eps->ip,"eps_");
391:   PetscLogObjectParent(eps,eps->ip);
392:   PetscPublishAll(eps);
393:   return(0);
394: }
395: 
398: /*@C
399:    EPSSetType - Selects the particular solver to be used in the EPS object. 

401:    Collective on EPS

403:    Input Parameters:
404: +  eps      - the eigensolver context
405: -  type     - a known method

407:    Options Database Key:
408: .  -eps_type <method> - Sets the method; use -help for a list 
409:     of available methods 
410:     
411:    Notes:  
412:    See "slepc/include/slepceps.h" for available methods. The default
413:    is EPSKRYLOVSCHUR.

415:    Normally, it is best to use the EPSSetFromOptions() command and
416:    then set the EPS type from the options database rather than by using
417:    this routine.  Using the options database provides the user with
418:    maximum flexibility in evaluating the different available methods.
419:    The EPSSetType() routine is provided for those situations where it
420:    is necessary to set the iterative solver independently of the command
421:    line or options database. 

423:    Level: intermediate

425: .seealso: STSetType(), EPSType
426: @*/
427: PetscErrorCode EPSSetType(EPS eps,const EPSType type)
428: {
429:   PetscErrorCode ierr,(*r)(EPS);
430:   PetscTruth match;


436:   PetscTypeCompare((PetscObject)eps,type,&match);
437:   if (match) return(0);

439:   if (eps->data) {
440:     /* destroy the old private EPS context */
441:     (*eps->ops->destroy)(eps);
442:     eps->data = 0;
443:   }

445:   PetscFListFind(EPSList,((PetscObject)eps)->comm,type,(void (**)(void)) &r);

447:   if (!r) SETERRQ1(1,"Unknown EPS type given: %s",type);

449:   eps->setupcalled = 0;
450:   PetscMemzero(eps->ops,sizeof(struct _EPSOps));
451:   (*r)(eps);

453:   PetscObjectChangeTypeName((PetscObject)eps,type);
454:   return(0);
455: }

459: /*@C
460:    EPSGetType - Gets the EPS type as a string from the EPS object.

462:    Not Collective

464:    Input Parameter:
465: .  eps - the eigensolver context 

467:    Output Parameter:
468: .  name - name of EPS method 

470:    Level: intermediate

472: .seealso: EPSSetType()
473: @*/
474: PetscErrorCode EPSGetType(EPS eps,const EPSType *type)
475: {
479:   *type = ((PetscObject)eps)->type_name;
480:   return(0);
481: }

483: /*MC
484:    EPSRegisterDynamic - Adds a method to the eigenproblem solver package.

486:    Synopsis:
487:    EPSRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(EPS))

489:    Not Collective

491:    Input Parameters:
492: +  name_solver - name of a new user-defined solver
493: .  path - path (either absolute or relative) the library containing this solver
494: .  name_create - name of routine to create the solver context
495: -  routine_create - routine to create the solver context

497:    Notes:
498:    EPSRegisterDynamic() may be called multiple times to add several user-defined solvers.

500:    If dynamic libraries are used, then the fourth input argument (routine_create)
501:    is ignored.

503:    Sample usage:
504: .vb
505:    EPSRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,
506:                "MySolverCreate",MySolverCreate);
507: .ve

509:    Then, your solver can be chosen with the procedural interface via
510: $     EPSSetType(eps,"my_solver")
511:    or at runtime via the option
512: $     -eps_type my_solver

514:    Level: advanced

516:    Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
517:    and others of the form ${any_environmental_variable} occuring in pathname will be 
518:    replaced with appropriate values.

520: .seealso: EPSRegisterDestroy(), EPSRegisterAll()

522: M*/

526: /*@C
527:   EPSRegister - See EPSRegisterDynamic()

529:   Level: advanced
530: @*/
531: PetscErrorCode EPSRegister(const char *sname,const char *path,const char *name,PetscErrorCode (*function)(EPS))
532: {
534:   char           fullname[256];

537:   PetscFListConcat(path,name,fullname);
538:   PetscFListAdd(&EPSList,sname,fullname,(void (*)(void))function);
539:   return(0);
540: }

544: /*@
545:    EPSRegisterDestroy - Frees the list of EPS methods that were
546:    registered by EPSRegisterDynamic().

548:    Not Collective

550:    Level: advanced

552: .seealso: EPSRegisterDynamic(), EPSRegisterAll()
553: @*/
554: PetscErrorCode EPSRegisterDestroy(void)
555: {

559:   PetscFListDestroy(&EPSList);
560:   EPSRegisterAll(PETSC_NULL);
561:   return(0);
562: }

566: /*@
567:    EPSDestroy - Destroys the EPS context.

569:    Collective on EPS

571:    Input Parameter:
572: .  eps - eigensolver context obtained from EPSCreate()

574:    Level: beginner

576: .seealso: EPSCreate(), EPSSetUp(), EPSSolve()
577: @*/
578: PetscErrorCode EPSDestroy(EPS eps)
579: {

584:   if (--((PetscObject)eps)->refct > 0) return(0);

586:   /* if memory was published with AMS then destroy it */
587:   PetscObjectDepublish(eps);

589:   STDestroy(eps->OP);
590:   IPDestroy(eps->ip);

592:   if (eps->ops->destroy) {
593:     (*eps->ops->destroy)(eps);
594:   }
595: 
596:   PetscFree(eps->T);
597:   PetscFree(eps->Tl);
598:   PetscFree(eps->perm);
599:   if (eps->rand) {
600:     PetscRandomDestroy(eps->rand);
601:   }

603:   if (eps->D) {
604:     VecDestroy(eps->D);
605:   }

607:   EPSRemoveDeflationSpace(eps);
608:   EPSMonitorCancel(eps);

610:   PetscHeaderDestroy(eps);
611:   return(0);
612: }

616: /*@
617:    EPSSetTarget - Sets the value of the target.

619:    Collective on EPS

621:    Input Parameters:
622: +  eps    - eigensolver context
623: -  target - the value of the target

625:    Notes:
626:    The target is a scalar value used to determine the portion of the spectrum
627:    of interest. It is used in combination with EPSSetWhichEigenpairs().
628:    
629:    Level: beginner

631: .seealso: EPSGetTarget(), EPSSetWhichEigenpairs()
632: @*/
633: PetscErrorCode EPSSetTarget(EPS eps,PetscScalar target)
634: {

639:   eps->target = target;
640:   STSetDefaultShift(eps->OP,target);
641:   return(0);
642: }

646: /*@
647:    EPSGetTarget - Gets the value of the target.

649:    Not collective

651:    Input Parameter:
652: .  eps - eigensolver context

654:    Output Parameter:
655: .  target - the value of the target

657:    Level: beginner

659:    Note:
660:    If the target was not set by the user, then zero is returned.

662: .seealso: EPSSetTarget()
663: @*/
664: PetscErrorCode EPSGetTarget(EPS eps,PetscScalar* target)
665: {
668:   if (target) {
669:     *target = eps->target;
670:   }
671:   return(0);
672: }

676: /*@
677:    EPSSetST - Associates a spectral transformation object to the
678:    eigensolver. 

680:    Collective on EPS and ST

682:    Input Parameters:
683: +  eps - eigensolver context obtained from EPSCreate()
684: -  st   - the spectral transformation object

686:    Note:
687:    Use EPSGetST() to retrieve the spectral transformation context (for example,
688:    to free it at the end of the computations).

690:    Level: advanced

692: .seealso: EPSGetST()
693: @*/
694: PetscErrorCode EPSSetST(EPS eps,ST st)
695: {

702:   PetscObjectReference((PetscObject)st);
703:   STDestroy(eps->OP);
704:   eps->OP = st;
705:   return(0);
706: }

710: /*@C
711:    EPSGetST - Obtain the spectral transformation (ST) object associated
712:    to the eigensolver object.

714:    Not Collective

716:    Input Parameters:
717: .  eps - eigensolver context obtained from EPSCreate()

719:    Output Parameter:
720: .  st - spectral transformation context

722:    Level: beginner

724: .seealso: EPSSetST()
725: @*/
726: PetscErrorCode EPSGetST(EPS eps, ST *st)
727: {
731:   *st = eps->OP;
732:   return(0);
733: }

737: /*@
738:    EPSSetIP - Associates an inner product object to the eigensolver. 

740:    Collective on EPS and IP

742:    Input Parameters:
743: +  eps - eigensolver context obtained from EPSCreate()
744: -  ip  - the inner product object

746:    Note:
747:    Use EPSGetIP() to retrieve the inner product context (for example,
748:    to free it at the end of the computations).

750:    Level: advanced

752: .seealso: EPSGetIP()
753: @*/
754: PetscErrorCode EPSSetIP(EPS eps,IP ip)
755: {

762:   PetscObjectReference((PetscObject)ip);
763:   IPDestroy(eps->ip);
764:   eps->ip = ip;
765:   return(0);
766: }

770: /*@C
771:    EPSGetIP - Obtain the inner product object associated
772:    to the eigensolver object.

774:    Not Collective

776:    Input Parameters:
777: .  eps - eigensolver context obtained from EPSCreate()

779:    Output Parameter:
780: .  ip - inner product context

782:    Level: advanced

784: .seealso: EPSSetIP()
785: @*/
786: PetscErrorCode EPSGetIP(EPS eps,IP *ip)
787: {
791:   *ip = eps->ip;
792:   return(0);
793: }

797: /*@
798:    EPSIsGeneralized - Ask if the EPS object corresponds to a generalized 
799:    eigenvalue problem.

801:    Not collective

803:    Input Parameter:
804: .  eps - the eigenproblem solver context

806:    Output Parameter:
807: .  is - the answer

809:    Level: intermediate

811: @*/
812: PetscErrorCode EPSIsGeneralized(EPS eps,PetscTruth* is)
813: {
815:   Mat            B;

819:   STGetOperators(eps->OP,PETSC_NULL,&B);
820:   if( B ) *is = PETSC_TRUE;
821:   else *is = PETSC_FALSE;
822:   if( eps->setupcalled ) {
823:     if( eps->isgeneralized != *is ) {
824:       SETERRQ(0,"Warning: Inconsistent EPS state");
825:     }
826:   }
827:   return(0);
828: }

832: /*@
833:    EPSIsHermitian - Ask if the EPS object corresponds to a Hermitian 
834:    eigenvalue problem.

836:    Not collective

838:    Input Parameter:
839: .  eps - the eigenproblem solver context

841:    Output Parameter:
842: .  is - the answer

844:    Level: intermediate

846: @*/
847: PetscErrorCode EPSIsHermitian(EPS eps,PetscTruth* is)
848: {
851:   if( eps->ishermitian ) *is = PETSC_TRUE;
852:   else *is = PETSC_FALSE;
853:   return(0);
854: }