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-2011, Universitat 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> /*I "slepceps.h" I*/
26: PetscFList EPSList = 0;
27: PetscBool EPSRegisterAllCalled = PETSC_FALSE;
28: PetscClassId EPS_CLASSID = 0;
29: PetscLogEvent EPS_SetUp = 0,EPS_Solve = 0,EPS_Dense = 0;
30: static PetscBool EPSPackageInitialized = PETSC_FALSE;
32: const char *EPSPowerShiftTypes[] = {"CONSTANT","RAYLEIGH","WILKINSON","EPSPowerShiftType","EPS_POWER_SHIFT_",0};
33: const char *EPSLanczosReorthogTypes[] = {"LOCAL","FULL","SELECTIVE","PERIODIC","PARTIAL","DELAYED","EPSLanczosReorthogType","EPS_LANCZOS_REORTHOG_",0};
34: const char *EPSPRIMMEMethods[] = {"DYNAMIC","DEFAULT_MIN_TIME","DEFAULT_MIN_MATVECS","ARNOLDI","GD","GD_PLUSK","GD_OLSEN_PLUSK","JD_OLSEN_PLUSK","RQI","JDQR","JDQMR","JDQMR_ETOL","SUBSPACE_ITERATION","LOBPCG_ORTHOBASIS","LOBPCG_ORTHOBASISW","EPSPRIMMEMethod","EPS_PRIMME_",0};
38: /*@C
39: EPSFinalizePackage - This function destroys everything in the Slepc interface to the EPS package. It is
40: called from SlepcFinalize().
42: Level: developer
44: .seealso: SlepcFinalize()
45: @*/
46: PetscErrorCode EPSFinalizePackage(void)
47: {
49: EPSPackageInitialized = PETSC_FALSE;
50: EPSList = 0;
51: EPSRegisterAllCalled = PETSC_FALSE;
52: return(0);
53: }
57: /*@C
58: EPSInitializePackage - This function initializes everything in the EPS package. It is called
59: from PetscDLLibraryRegister() when using dynamic libraries, and on the first call to EPSCreate()
60: when using static libraries.
62: Input Parameter:
63: path - The dynamic library path, or PETSC_NULL
65: Level: developer
67: .seealso: SlepcInitialize()
68: @*/
69: PetscErrorCode EPSInitializePackage(const char *path) {
70: char logList[256];
71: char *className;
72: PetscBool opt;
76: if (EPSPackageInitialized) return(0);
77: EPSPackageInitialized = PETSC_TRUE;
78: /* Register Classes */
79: PetscClassIdRegister("Eigenproblem Solver",&EPS_CLASSID);
80: /* Register Constructors */
81: EPSRegisterAll(path);
82: /* Register Events */
83: PetscLogEventRegister("EPSSetUp",EPS_CLASSID,&EPS_SetUp);
84: PetscLogEventRegister("EPSSolve",EPS_CLASSID,&EPS_Solve);
85: PetscLogEventRegister("EPSDense",EPS_CLASSID,&EPS_Dense);
86: /* Process info exclusions */
87: PetscOptionsGetString(PETSC_NULL,"-info_exclude",logList,256,&opt);
88: if (opt) {
89: PetscStrstr(logList,"eps",&className);
90: if (className) {
91: PetscInfoDeactivateClass(EPS_CLASSID);
92: }
93: }
94: /* Process summary exclusions */
95: PetscOptionsGetString(PETSC_NULL,"-log_summary_exclude",logList,256,&opt);
96: if (opt) {
97: PetscStrstr(logList,"eps",&className);
98: if (className) {
99: PetscLogEventDeactivateClass(EPS_CLASSID);
100: }
101: }
102: PetscRegisterFinalize(EPSFinalizePackage);
103: return(0);
104: }
108: /*@C
109: EPSView - Prints the EPS data structure.
111: Collective on EPS
113: Input Parameters:
114: + eps - the eigenproblem solver context
115: - viewer - optional visualization context
117: Options Database Key:
118: . -eps_view - Calls EPSView() at end of EPSSolve()
120: Note:
121: The available visualization contexts include
122: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
123: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
124: output where only the first processor opens
125: the file. All other processors send their
126: data to the first processor to print.
128: The user can open an alternative visualization context with
129: PetscViewerASCIIOpen() - output to a specified file.
131: Level: beginner
133: .seealso: STView(), PetscViewerASCIIOpen()
134: @*/
135: PetscErrorCode EPSView(EPS eps,PetscViewer viewer)
136: {
138: const char *type,*extr,*bal;
139: PetscBool isascii;
143: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(((PetscObject)eps)->comm);
147: #if defined(PETSC_USE_COMPLEX)
148: #define HERM "hermitian"
149: #else
150: #define HERM "symmetric"
151: #endif
152: PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
153: if (isascii) {
154: PetscObjectPrintClassNamePrefixType((PetscObject)eps,viewer,"EPS Object");
155: if (eps->ops->view) {
156: PetscViewerASCIIPushTab(viewer);
157: (*eps->ops->view)(eps,viewer);
158: PetscViewerASCIIPopTab(viewer);
159: }
160: if (eps->problem_type) {
161: switch (eps->problem_type) {
162: case EPS_HEP: type = HERM " eigenvalue problem"; break;
163: case EPS_GHEP: type = "generalized " HERM " eigenvalue problem"; break;
164: case EPS_NHEP: type = "non-" HERM " eigenvalue problem"; break;
165: case EPS_GNHEP: type = "generalized non-" HERM " eigenvalue problem"; break;
166: case EPS_PGNHEP: type = "generalized non-" HERM " eigenvalue problem with " HERM " positive definite B"; break;
167: default: SETERRQ(((PetscObject)eps)->comm,1,"Wrong value of eps->problem_type");
168: }
169: } else type = "not yet set";
170: PetscViewerASCIIPrintf(viewer," problem type: %s\n",type);
171: if (eps->extraction) {
172: switch (eps->extraction) {
173: case EPS_RITZ: extr = "Rayleigh-Ritz"; break;
174: case EPS_HARMONIC: extr = "harmonic Ritz"; break;
175: case EPS_HARMONIC_RELATIVE:extr = "relative harmonic Ritz"; break;
176: case EPS_HARMONIC_RIGHT: extr = "right harmonic Ritz"; break;
177: case EPS_HARMONIC_LARGEST: extr = "largest harmonic Ritz"; break;
178: case EPS_REFINED: extr = "refined Ritz"; break;
179: case EPS_REFINED_HARMONIC: extr = "refined harmonic Ritz"; break;
180: default: SETERRQ(((PetscObject)eps)->comm,1,"Wrong value of eps->extraction");
181: }
182: PetscViewerASCIIPrintf(viewer," extraction type: %s\n",extr);
183: }
184: if (eps->balance && !eps->ishermitian && eps->balance!=EPS_BALANCE_NONE) {
185: switch (eps->balance) {
186: case EPS_BALANCE_ONESIDE: bal = "one-sided Krylov"; break;
187: case EPS_BALANCE_TWOSIDE: bal = "two-sided Krylov"; break;
188: case EPS_BALANCE_USER: bal = "user-defined matrix"; break;
189: default: SETERRQ(((PetscObject)eps)->comm,1,"Wrong value of eps->balance");
190: }
191: PetscViewerASCIIPrintf(viewer," balancing enabled: %s",bal);
192: if (eps->balance==EPS_BALANCE_ONESIDE || eps->balance==EPS_BALANCE_TWOSIDE) {
193: PetscViewerASCIIPrintf(viewer,", with its=%D",eps->balance_its);
194: }
195: if (eps->balance==EPS_BALANCE_TWOSIDE && eps->balance_cutoff!=0.0) {
196: PetscViewerASCIIPrintf(viewer," and cutoff=%G",eps->balance_cutoff);
197: }
198: PetscViewerASCIIPrintf(viewer,"\n");
199: }
200: PetscViewerASCIIPrintf(viewer," selected portion of the spectrum: ");
201: if (!eps->which) {
202: PetscViewerASCIIPrintf(viewer,"not yet set\n");
203: } else switch (eps->which) {
204: case EPS_WHICH_USER:
205: PetscViewerASCIIPrintf(viewer,"user defined\n");
206: break;
207: case EPS_TARGET_MAGNITUDE:
208: #if !defined(PETSC_USE_COMPLEX)
209: PetscViewerASCIIPrintf(viewer,"closest to target: %G (in magnitude)\n",eps->target);
210: #else
211: PetscViewerASCIIPrintf(viewer,"closest to target: %G+%G i (in magnitude)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
212: #endif
213: break;
214: case EPS_TARGET_REAL:
215: #if !defined(PETSC_USE_COMPLEX)
216: PetscViewerASCIIPrintf(viewer,"closest to target: %G (along the real axis)\n",eps->target);
217: #else
218: PetscViewerASCIIPrintf(viewer,"closest to target: %G+%G i (along the real axis)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
219: #endif
220: break;
221: #if defined(PETSC_USE_COMPLEX)
222: case EPS_TARGET_IMAGINARY:
223: PetscViewerASCIIPrintf(viewer,"closest to target: %G+%G i (along the imaginary axis)\n",PetscRealPart(eps->target),PetscImaginaryPart(eps->target));
224: break;
225: #endif
226: case EPS_LARGEST_MAGNITUDE:
227: PetscViewerASCIIPrintf(viewer,"largest eigenvalues in magnitude\n");
228: break;
229: case EPS_SMALLEST_MAGNITUDE:
230: PetscViewerASCIIPrintf(viewer,"smallest eigenvalues in magnitude\n");
231: break;
232: case EPS_LARGEST_REAL:
233: PetscViewerASCIIPrintf(viewer,"largest real parts\n");
234: break;
235: case EPS_SMALLEST_REAL:
236: PetscViewerASCIIPrintf(viewer,"smallest real parts\n");
237: break;
238: case EPS_LARGEST_IMAGINARY:
239: PetscViewerASCIIPrintf(viewer,"largest imaginary parts\n");
240: break;
241: case EPS_SMALLEST_IMAGINARY:
242: PetscViewerASCIIPrintf(viewer,"smallest imaginary parts\n");
243: break;
244: case EPS_ALL:
245: PetscViewerASCIIPrintf(viewer,"all eigenvalues in interval [%G,%G]\n",eps->inta,eps->intb);
246: break;
247: default: SETERRQ(((PetscObject)eps)->comm,1,"Wrong value of eps->which");
248: }
249: if (eps->leftvecs) {
250: PetscViewerASCIIPrintf(viewer," computing left eigenvectors also\n");
251: }
252: if (eps->trueres) {
253: PetscViewerASCIIPrintf(viewer," computing true residuals explicitly\n");
254: }
255: if (eps->trackall) {
256: PetscViewerASCIIPrintf(viewer," computing all residuals (for tracking convergence)\n");
257: }
258: PetscViewerASCIIPrintf(viewer," number of eigenvalues (nev): %D\n",eps->nev);
259: PetscViewerASCIIPrintf(viewer," number of column vectors (ncv): %D\n",eps->ncv);
260: PetscViewerASCIIPrintf(viewer," maximum dimension of projected problem (mpd): %D\n",eps->mpd);
261: PetscViewerASCIIPrintf(viewer," maximum number of iterations: %D\n",eps->max_it);
262: PetscViewerASCIIPrintf(viewer," tolerance: %G\n",eps->tol);
263: PetscViewerASCIIPrintf(viewer," convergence test: ");
264: switch(eps->conv) {
265: case EPS_CONV_ABS:
266: PetscViewerASCIIPrintf(viewer,"absolute\n");break;
267: case EPS_CONV_EIG:
268: PetscViewerASCIIPrintf(viewer,"relative to the eigenvalue\n");break;
269: case EPS_CONV_NORM:
270: PetscViewerASCIIPrintf(viewer,"relative to the eigenvalue and matrix norms\n");break;
271: default:
272: PetscViewerASCIIPrintf(viewer,"user-defined\n");break;
273: }
274: if (eps->nini!=0) {
275: PetscViewerASCIIPrintf(viewer," dimension of user-provided initial space: %D\n",PetscAbs(eps->nini));
276: }
277: if (eps->ninil!=0) {
278: PetscViewerASCIIPrintf(viewer," dimension of user-provided initial left space: %D\n",PetscAbs(eps->ninil));
279: }
280: if (eps->nds>0) {
281: PetscViewerASCIIPrintf(viewer," dimension of user-provided deflation space: %D\n",eps->nds);
282: }
283: PetscViewerASCIIPrintf(viewer," estimates of matrix norms (%s): norm(A)=%G",eps->adaptive?"adaptive":"constant",eps->nrma);
284: if (eps->isgeneralized) {
285: PetscViewerASCIIPrintf(viewer,", norm(B)=%G",eps->nrmb);
286: }
287: PetscViewerASCIIPrintf(viewer,"\n");
288: } else {
289: if (eps->ops->view) {
290: (*eps->ops->view)(eps,viewer);
291: }
292: }
293: if (!eps->ip) { EPSGetIP(eps,&eps->ip); }
294: IPView(eps->ip,viewer);
295: if (!eps->OP) { EPSGetST(eps,&eps->OP); }
296: STView(eps->OP,viewer);
297: return(0);
298: }
302: /*@
303: EPSPrintSolution - Prints the computed eigenvalues.
305: Collective on EPS
307: Input Parameters:
308: + eps - the eigensolver context
309: - viewer - optional visualization context
311: Options Database:
312: . -eps_terse - print only minimal information
314: Note:
315: By default, this function prints a table with eigenvalues and associated
316: relative errors. With -eps_terse only the eigenvalues are printed.
318: Level: intermediate
320: .seealso: PetscViewerASCIIOpen()
321: @*/
322: PetscErrorCode EPSPrintSolution(EPS eps,PetscViewer viewer)
323: {
324: PetscBool terse,errok,isascii;
325: PetscReal error,re,im;
326: PetscScalar kr,ki;
327: PetscInt i,j;
332: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(((PetscObject)eps)->comm);
335: if (!eps->eigr || !eps->eigi || !eps->V) {
336: SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_WRONGSTATE,"EPSSolve must be called first");
337: }
338: PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
339: if (!isascii) return(0);
341: PetscOptionsHasName(PETSC_NULL,"-eps_terse",&terse);
342: if (terse) {
343: if (eps->nconv<eps->nev) {
344: PetscViewerASCIIPrintf(viewer," Problem: less than %D eigenvalues converged\n\n",eps->nev);
345: } else {
346: errok = PETSC_TRUE;
347: for (i=0;i<eps->nev;i++) {
348: EPSComputeRelativeError(eps,i,&error);
349: errok = (errok && error<eps->tol)? PETSC_TRUE: PETSC_FALSE;
350: }
351: if (errok) {
352: PetscViewerASCIIPrintf(viewer," All requested eigenvalues computed up to the required tolerance:");
353: for (i=0;i<=(eps->nev-1)/8;i++) {
354: PetscViewerASCIIPrintf(viewer,"\n ");
355: for (j=0;j<PetscMin(8,eps->nev-8*i);j++) {
356: EPSGetEigenpair(eps,8*i+j,&kr,&ki,PETSC_NULL,PETSC_NULL);
357: #if defined(PETSC_USE_COMPLEX)
358: re = PetscRealPart(kr);
359: im = PetscImaginaryPart(kr);
360: #else
361: re = kr;
362: im = ki;
363: #endif
364: if (PetscAbs(re)/PetscAbs(im)<PETSC_SMALL) re = 0.0;
365: if (PetscAbs(im)/PetscAbs(re)<PETSC_SMALL) im = 0.0;
366: if (im!=0.0) {
367: PetscViewerASCIIPrintf(viewer,"%.5F%+.5Fi",re,im);
368: } else {
369: PetscViewerASCIIPrintf(viewer,"%.5F",re);
370: }
371: if (8*i+j+1<eps->nev) { PetscViewerASCIIPrintf(viewer,", "); }
372: }
373: }
374: PetscViewerASCIIPrintf(viewer,"\n\n");
375: } else {
376: PetscViewerASCIIPrintf(viewer," Problem: some of the first %D relative errors are higher than the tolerance\n\n",eps->nev);
377: }
378: }
379: } else {
380: PetscViewerASCIIPrintf(viewer," Number of converged approximate eigenpairs: %D\n\n",eps->nconv);
381: if (eps->nconv>0) {
382: PetscViewerASCIIPrintf(viewer,
383: " k ||Ax-k%sx||/||kx||\n"
384: " ----------------- ------------------\n",eps->isgeneralized?"B":"");
385: for (i=0;i<eps->nconv;i++) {
386: EPSGetEigenpair(eps,i,&kr,&ki,PETSC_NULL,PETSC_NULL);
387: EPSComputeRelativeError(eps,i,&error);
388: #if defined(PETSC_USE_COMPLEX)
389: re = PetscRealPart(kr);
390: im = PetscImaginaryPart(kr);
391: #else
392: re = kr;
393: im = ki;
394: #endif
395: if (im!=0.0) {
396: PetscViewerASCIIPrintf(viewer," % 9F%+9F i %12G\n",re,im,error);
397: } else {
398: PetscViewerASCIIPrintf(viewer," % 12F %12G\n",re,error);
399: }
400: }
401: PetscViewerASCIIPrintf(viewer,"\n");
402: }
403: }
404: return(0);
405: }
409: /*@C
410: EPSCreate - Creates the default EPS context.
412: Collective on MPI_Comm
414: Input Parameter:
415: . comm - MPI communicator
417: Output Parameter:
418: . eps - location to put the EPS context
420: Note:
421: The default EPS type is EPSKRYLOVSCHUR
423: Level: beginner
425: .seealso: EPSSetUp(), EPSSolve(), EPSDestroy(), EPS
426: @*/
427: PetscErrorCode EPSCreate(MPI_Comm comm,EPS *outeps)
428: {
430: EPS eps;
434: *outeps = 0;
436: PetscHeaderCreate(eps,_p_EPS,struct _EPSOps,EPS_CLASSID,-1,"EPS","Eigenvalue Problem Solver","EPS",comm,EPSDestroy,EPSView);
438: eps->max_it = 0;
439: eps->nev = 1;
440: eps->ncv = 0;
441: eps->mpd = 0;
442: eps->allocated_ncv = 0;
443: eps->nini = 0;
444: eps->ninil = 0;
445: eps->nds = 0;
446: eps->tol = PETSC_DEFAULT;
447: eps->conv = EPS_CONV_EIG;
448: eps->conv_func = EPSEigRelativeConverged;
449: eps->conv_ctx = PETSC_NULL;
450: eps->which = (EPSWhich)0;
451: eps->which_func = PETSC_NULL;
452: eps->which_ctx = PETSC_NULL;
453: eps->leftvecs = PETSC_FALSE;
454: eps->trueres = PETSC_FALSE;
455: eps->trackall = PETSC_FALSE;
456: eps->target = 0.0;
457: eps->inta = 0.0;
458: eps->intb = 0.0;
459: eps->evecsavailable = PETSC_FALSE;
460: eps->problem_type = (EPSProblemType)0;
461: eps->extraction = (EPSExtraction)0;
462: eps->balance = (EPSBalance)0;
463: eps->balance_its = 5;
464: eps->balance_cutoff = 1e-8;
465: eps->nrma = 1.0;
466: eps->nrmb = 1.0;
467: eps->adaptive = PETSC_FALSE;
469: eps->V = 0;
470: eps->W = 0;
471: eps->T = 0;
472: eps->D = 0;
473: eps->DS = 0;
474: eps->IS = 0;
475: eps->ISL = 0;
476: eps->t = 0;
477: eps->ds_ortho = PETSC_FALSE;
478: eps->eigr = 0;
479: eps->eigi = 0;
480: eps->errest = 0;
481: eps->errest_left = 0;
482: eps->OP = 0;
483: eps->ip = 0;
484: eps->rand = 0;
485: eps->data = 0;
486: eps->nconv = 0;
487: eps->its = 0;
488: eps->perm = PETSC_NULL;
490: eps->nwork = 0;
491: eps->work = 0;
492: eps->isgeneralized = PETSC_FALSE;
493: eps->ishermitian = PETSC_FALSE;
494: eps->ispositive = PETSC_FALSE;
495: eps->setupcalled = 0;
496: eps->reason = EPS_CONVERGED_ITERATING;
497: eps->numbermonitors = 0;
499: PetscRandomCreate(comm,&eps->rand);
500: PetscRandomSetSeed(eps->rand,0x12345678);
501: PetscLogObjectParent(eps,eps->rand);
502: *outeps = eps;
503: return(0);
504: }
505:
508: /*@C
509: EPSSetType - Selects the particular solver to be used in the EPS object.
511: Logically Collective on EPS
513: Input Parameters:
514: + eps - the eigensolver context
515: - type - a known method
517: Options Database Key:
518: . -eps_type <method> - Sets the method; use -help for a list
519: of available methods
520:
521: Notes:
522: See "slepc/include/slepceps.h" for available methods. The default
523: is EPSKRYLOVSCHUR.
525: Normally, it is best to use the EPSSetFromOptions() command and
526: then set the EPS type from the options database rather than by using
527: this routine. Using the options database provides the user with
528: maximum flexibility in evaluating the different available methods.
529: The EPSSetType() routine is provided for those situations where it
530: is necessary to set the iterative solver independently of the command
531: line or options database.
533: Level: intermediate
535: .seealso: STSetType(), EPSType
536: @*/
537: PetscErrorCode EPSSetType(EPS eps,const EPSType type)
538: {
539: PetscErrorCode ierr,(*r)(EPS);
540: PetscBool match;
546: PetscTypeCompare((PetscObject)eps,type,&match);
547: if (match) return(0);
549: PetscFListFind(EPSList,((PetscObject)eps)->comm,type,PETSC_TRUE,(void (**)(void)) &r);
550: if (!r) SETERRQ1(((PetscObject)eps)->comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown EPS type given: %s",type);
552: if (eps->ops->destroy) { (*eps->ops->destroy)(eps); }
553: PetscMemzero(eps->ops,sizeof(struct _EPSOps));
555: eps->setupcalled = 0;
556: PetscObjectChangeTypeName((PetscObject)eps,type);
557: (*r)(eps);
558: return(0);
559: }
563: /*@C
564: EPSGetType - Gets the EPS type as a string from the EPS object.
566: Not Collective
568: Input Parameter:
569: . eps - the eigensolver context
571: Output Parameter:
572: . name - name of EPS method
574: Level: intermediate
576: .seealso: EPSSetType()
577: @*/
578: PetscErrorCode EPSGetType(EPS eps,const EPSType *type)
579: {
583: *type = ((PetscObject)eps)->type_name;
584: return(0);
585: }
589: /*@C
590: EPSRegister - See EPSRegisterDynamic()
592: Level: advanced
593: @*/
594: PetscErrorCode EPSRegister(const char *sname,const char *path,const char *name,PetscErrorCode (*function)(EPS))
595: {
597: char fullname[PETSC_MAX_PATH_LEN];
600: PetscFListConcat(path,name,fullname);
601: PetscFListAdd(&EPSList,sname,fullname,(void (*)(void))function);
602: return(0);
603: }
607: /*@
608: EPSRegisterDestroy - Frees the list of EPS methods that were
609: registered by EPSRegisterDynamic().
611: Not Collective
613: Level: advanced
615: .seealso: EPSRegisterDynamic(), EPSRegisterAll()
616: @*/
617: PetscErrorCode EPSRegisterDestroy(void)
618: {
622: PetscFListDestroy(&EPSList);
623: EPSRegisterAllCalled = PETSC_FALSE;
624: return(0);
625: }
629: /*@
630: EPSReset - Resets the EPS context to the setupcalled=0 state and removes any
631: allocated objects.
633: Collective on EPS
635: Input Parameter:
636: . eps - eigensolver context obtained from EPSCreate()
638: Level: advanced
640: .seealso: EPSDestroy()
641: @*/
642: PetscErrorCode EPSReset(EPS eps)
643: {
648: if (eps->ops->reset) { (eps->ops->reset)(eps); }
649: if (eps->OP) { STReset(eps->OP); }
650: if (eps->ip) { IPReset(eps->ip); }
651: VecDestroy(&eps->t);
652: VecDestroy(&eps->D);
653: eps->setupcalled = 0;
654: return(0);
655: }
659: /*@C
660: EPSDestroy - Destroys the EPS context.
662: Collective on EPS
664: Input Parameter:
665: . eps - eigensolver context obtained from EPSCreate()
667: Level: beginner
669: .seealso: EPSCreate(), EPSSetUp(), EPSSolve()
670: @*/
671: PetscErrorCode EPSDestroy(EPS *eps)
672: {
676: if (!*eps) return(0);
678: if (--((PetscObject)(*eps))->refct > 0) { *eps = 0; return(0); }
679: EPSReset(*eps);
680: PetscObjectDepublish(*eps);
681: if ((*eps)->ops->destroy) { (*(*eps)->ops->destroy)(*eps); }
682: STDestroy(&(*eps)->OP);
683: IPDestroy(&(*eps)->ip);
684: PetscRandomDestroy(&(*eps)->rand);
685: EPSRemoveDeflationSpace(*eps);
686: EPSMonitorCancel(*eps);
687: PetscHeaderDestroy(eps);
688: return(0);
689: }
693: /*@
694: EPSSetTarget - Sets the value of the target.
696: Logically Collective on EPS
698: Input Parameters:
699: + eps - eigensolver context
700: - target - the value of the target
702: Notes:
703: The target is a scalar value used to determine the portion of the spectrum
704: of interest. It is used in combination with EPSSetWhichEigenpairs().
705:
706: Level: beginner
708: .seealso: EPSGetTarget(), EPSSetWhichEigenpairs()
709: @*/
710: PetscErrorCode EPSSetTarget(EPS eps,PetscScalar target)
711: {
717: eps->target = target;
718: if (!eps->OP) { EPSGetST(eps,&eps->OP); }
719: STSetDefaultShift(eps->OP,target);
720: return(0);
721: }
725: /*@
726: EPSGetTarget - Gets the value of the target.
728: Not Collective
730: Input Parameter:
731: . eps - eigensolver context
733: Output Parameter:
734: . target - the value of the target
736: Level: beginner
738: Note:
739: If the target was not set by the user, then zero is returned.
741: .seealso: EPSSetTarget()
742: @*/
743: PetscErrorCode EPSGetTarget(EPS eps,PetscScalar* target)
744: {
748: *target = eps->target;
749: return(0);
750: }
754: /*@
755: EPSSetInterval - Defines the computational interval for spectrum slicing.
757: Logically Collective on EPS
759: Input Parameters:
760: + eps - eigensolver context
761: . inta - left end of the interval
762: - intb - right end of the interval
764: Options Database Key:
765: . -eps_interval <a,b> - set [a,b] as the interval of interest
767: Notes:
768: Spectrum slicing is a technique employed for computing all eigenvalues of
769: symmetric eigenproblems in a given interval. This function provides the
770: interval to be considered. It must be used in combination with EPS_ALL, see
771: EPSSetWhichEigenpairs().
773: In the command-line option, two values must be provided. For an open interval,
774: one can give an infinite, e.g., -eps_interval 1.0,inf or -eps_interval -inf,1.0.
775: An open interval in the programmatic interface can be specified with
776: PETSC_MAX_REAL and -PETSC_MAX_REAL.
777:
778: Level: intermediate
780: .seealso: EPSGetInterval(), EPSSetWhichEigenpairs()
781: @*/
782: PetscErrorCode EPSSetInterval(EPS eps,PetscReal inta,PetscReal intb)
783: {
788: if (inta>=intb) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_WRONG,"Badly defined interval, must be inta<intb");
789: eps->inta = inta;
790: eps->intb = intb;
791: return(0);
792: }
796: /*@
797: EPSGetInterval - Gets the computational interval for spectrum slicing.
799: Not Collective
801: Input Parameter:
802: . eps - eigensolver context
804: Output Parameters:
805: + inta - left end of the interval
806: - intb - right end of the interval
808: Level: intermediate
810: Note:
811: If the interval was not set by the user, then zeros are returned.
813: .seealso: EPSSetInterval()
814: @*/
815: PetscErrorCode EPSGetInterval(EPS eps,PetscReal* inta,PetscReal* intb)
816: {
821: if (inta) *inta = eps->inta;
822: if (intb) *intb = eps->intb;
823: return(0);
824: }
828: /*@
829: EPSSetST - Associates a spectral transformation object to the eigensolver.
831: Collective on EPS
833: Input Parameters:
834: + eps - eigensolver context obtained from EPSCreate()
835: - st - the spectral transformation object
837: Note:
838: Use EPSGetST() to retrieve the spectral transformation context (for example,
839: to free it at the end of the computations).
841: Level: developer
843: .seealso: EPSGetST()
844: @*/
845: PetscErrorCode EPSSetST(EPS eps,ST st)
846: {
853: PetscObjectReference((PetscObject)st);
854: STDestroy(&eps->OP);
855: eps->OP = st;
856: PetscLogObjectParent(eps,eps->OP);
857: return(0);
858: }
862: /*@C
863: EPSGetST - Obtain the spectral transformation (ST) object associated
864: to the eigensolver object.
866: Not Collective
868: Input Parameters:
869: . eps - eigensolver context obtained from EPSCreate()
871: Output Parameter:
872: . st - spectral transformation context
874: Level: beginner
876: .seealso: EPSSetST()
877: @*/
878: PetscErrorCode EPSGetST(EPS eps,ST *st)
879: {
885: if (!eps->OP) {
886: STCreate(((PetscObject)eps)->comm,&eps->OP);
887: PetscLogObjectParent(eps,eps->OP);
888: }
889: *st = eps->OP;
890: return(0);
891: }
895: /*@
896: EPSSetIP - Associates an inner product object to the eigensolver.
898: Collective on EPS
900: Input Parameters:
901: + eps - eigensolver context obtained from EPSCreate()
902: - ip - the inner product object
904: Note:
905: Use EPSGetIP() to retrieve the inner product context (for example,
906: to free it at the end of the computations).
908: Level: advanced
910: .seealso: EPSGetIP()
911: @*/
912: PetscErrorCode EPSSetIP(EPS eps,IP ip)
913: {
920: PetscObjectReference((PetscObject)ip);
921: IPDestroy(&eps->ip);
922: eps->ip = ip;
923: PetscLogObjectParent(eps,eps->ip);
924: return(0);
925: }
929: /*@C
930: EPSGetIP - Obtain the inner product object associated to the eigensolver object.
932: Not Collective
934: Input Parameters:
935: . eps - eigensolver context obtained from EPSCreate()
937: Output Parameter:
938: . ip - inner product context
940: Level: advanced
942: .seealso: EPSSetIP()
943: @*/
944: PetscErrorCode EPSGetIP(EPS eps,IP *ip)
945: {
951: if (!eps->ip) {
952: IPCreate(((PetscObject)eps)->comm,&eps->ip);
953: PetscLogObjectParent(eps,eps->ip);
954: }
955: *ip = eps->ip;
956: return(0);
957: }
961: /*@
962: EPSIsGeneralized - Ask if the EPS object corresponds to a generalized
963: eigenvalue problem.
965: Not collective
967: Input Parameter:
968: . eps - the eigenproblem solver context
970: Output Parameter:
971: . is - the answer
973: Level: intermediate
975: .seealso: EPSIsHermitian()
976: @*/
977: PetscErrorCode EPSIsGeneralized(EPS eps,PetscBool* is)
978: {
981: *is = eps->isgeneralized;
982: return(0);
983: }
987: /*@
988: EPSIsHermitian - Ask if the EPS object corresponds to a Hermitian
989: eigenvalue problem.
991: Not collective
993: Input Parameter:
994: . eps - the eigenproblem solver context
996: Output Parameter:
997: . is - the answer
999: Level: intermediate
1001: .seealso: EPSIsGeneralized()
1002: @*/
1003: PetscErrorCode EPSIsHermitian(EPS eps,PetscBool* is)
1004: {
1007: *is = eps->ishermitian;
1008: return(0);
1009: }