Line data Source code
1 : /*
2 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3 : SLEPc - Scalable Library for Eigenvalue Problem Computations
4 : Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
5 :
6 : This file is part of SLEPc.
7 : SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9 : */
10 : /*
11 : Basic EPS routines
12 : */
13 :
14 : #include <slepc/private/epsimpl.h> /*I "slepceps.h" I*/
15 :
16 : /* Logging support */
17 : PetscClassId EPS_CLASSID = 0;
18 : PetscLogEvent EPS_SetUp = 0,EPS_Solve = 0,EPS_CISS_SVD = 0;
19 :
20 : /* List of registered EPS routines */
21 : PetscFunctionList EPSList = NULL;
22 : PetscBool EPSRegisterAllCalled = PETSC_FALSE;
23 :
24 : /* List of registered EPS monitors */
25 : PetscFunctionList EPSMonitorList = NULL;
26 : PetscFunctionList EPSMonitorCreateList = NULL;
27 : PetscFunctionList EPSMonitorDestroyList = NULL;
28 : PetscBool EPSMonitorRegisterAllCalled = PETSC_FALSE;
29 :
30 : /*@
31 : EPSCreate - Creates the default EPS context.
32 :
33 : Collective
34 :
35 : Input Parameter:
36 : . comm - MPI communicator
37 :
38 : Output Parameter:
39 : . outeps - location to put the EPS context
40 :
41 : Note:
42 : The default EPS type is EPSKRYLOVSCHUR
43 :
44 : Level: beginner
45 :
46 : .seealso: EPSSetUp(), EPSSolve(), EPSDestroy(), EPS
47 : @*/
48 648 : PetscErrorCode EPSCreate(MPI_Comm comm,EPS *outeps)
49 : {
50 648 : EPS eps;
51 :
52 648 : PetscFunctionBegin;
53 648 : PetscAssertPointer(outeps,2);
54 648 : PetscCall(EPSInitializePackage());
55 648 : PetscCall(SlepcHeaderCreate(eps,EPS_CLASSID,"EPS","Eigenvalue Problem Solver","EPS",comm,EPSDestroy,EPSView));
56 :
57 648 : eps->max_it = PETSC_DETERMINE;
58 648 : eps->nev = 0;
59 648 : eps->ncv = PETSC_DETERMINE;
60 648 : eps->mpd = PETSC_DETERMINE;
61 648 : eps->nini = 0;
62 648 : eps->nds = 0;
63 648 : eps->target = 0.0;
64 648 : eps->tol = PETSC_DETERMINE;
65 648 : eps->thres = PETSC_MIN_REAL;
66 648 : eps->threlative = PETSC_FALSE;
67 648 : eps->conv = EPS_CONV_REL;
68 648 : eps->stop = EPS_STOP_BASIC;
69 648 : eps->which = (EPSWhich)0;
70 648 : eps->inta = 0.0;
71 648 : eps->intb = 0.0;
72 648 : eps->problem_type = (EPSProblemType)0;
73 648 : eps->extraction = EPS_RITZ;
74 648 : eps->balance = EPS_BALANCE_NONE;
75 648 : eps->balance_its = 5;
76 648 : eps->balance_cutoff = 1e-8;
77 648 : eps->trueres = PETSC_FALSE;
78 648 : eps->trackall = PETSC_FALSE;
79 648 : eps->purify = PETSC_TRUE;
80 648 : eps->twosided = PETSC_FALSE;
81 :
82 648 : eps->converged = EPSConvergedRelative;
83 648 : eps->convergeduser = NULL;
84 648 : eps->convergeddestroy= NULL;
85 648 : eps->stopping = EPSStoppingBasic;
86 648 : eps->stoppinguser = NULL;
87 648 : eps->stoppingdestroy = NULL;
88 648 : eps->arbitrary = NULL;
89 648 : eps->convergedctx = NULL;
90 648 : eps->stoppingctx = NULL;
91 648 : eps->arbitraryctx = NULL;
92 648 : eps->numbermonitors = 0;
93 :
94 648 : eps->st = NULL;
95 648 : eps->ds = NULL;
96 648 : eps->V = NULL;
97 648 : eps->W = NULL;
98 648 : eps->rg = NULL;
99 648 : eps->D = NULL;
100 648 : eps->IS = NULL;
101 648 : eps->ISL = NULL;
102 648 : eps->defl = NULL;
103 648 : eps->eigr = NULL;
104 648 : eps->eigi = NULL;
105 648 : eps->errest = NULL;
106 648 : eps->rr = NULL;
107 648 : eps->ri = NULL;
108 648 : eps->perm = NULL;
109 648 : eps->nwork = 0;
110 648 : eps->work = NULL;
111 648 : eps->data = NULL;
112 :
113 648 : eps->state = EPS_STATE_INITIAL;
114 648 : eps->categ = EPS_CATEGORY_KRYLOV;
115 648 : eps->nconv = 0;
116 648 : eps->its = 0;
117 648 : eps->nloc = 0;
118 648 : eps->nrma = 0.0;
119 648 : eps->nrmb = 0.0;
120 648 : eps->useds = PETSC_FALSE;
121 648 : eps->isgeneralized = PETSC_FALSE;
122 648 : eps->ispositive = PETSC_FALSE;
123 648 : eps->ishermitian = PETSC_FALSE;
124 648 : eps->isstructured = PETSC_FALSE;
125 648 : eps->reason = EPS_CONVERGED_ITERATING;
126 :
127 648 : PetscCall(PetscNew(&eps->sc));
128 648 : *outeps = eps;
129 648 : PetscFunctionReturn(PETSC_SUCCESS);
130 : }
131 :
132 : /*@
133 : EPSSetType - Selects the particular solver to be used in the EPS object.
134 :
135 : Logically Collective
136 :
137 : Input Parameters:
138 : + eps - the eigensolver context
139 : - type - a known method
140 :
141 : Options Database Key:
142 : . -eps_type <method> - Sets the method; use -help for a list
143 : of available methods
144 :
145 : Notes:
146 : See "slepc/include/slepceps.h" for available methods. The default
147 : is EPSKRYLOVSCHUR.
148 :
149 : Normally, it is best to use the EPSSetFromOptions() command and
150 : then set the EPS type from the options database rather than by using
151 : this routine. Using the options database provides the user with
152 : maximum flexibility in evaluating the different available methods.
153 : The EPSSetType() routine is provided for those situations where it
154 : is necessary to set the iterative solver independently of the command
155 : line or options database.
156 :
157 : Level: intermediate
158 :
159 : .seealso: STSetType(), EPSType
160 : @*/
161 675 : PetscErrorCode EPSSetType(EPS eps,EPSType type)
162 : {
163 675 : PetscErrorCode (*r)(EPS);
164 675 : PetscBool match;
165 :
166 675 : PetscFunctionBegin;
167 675 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
168 675 : PetscAssertPointer(type,2);
169 :
170 675 : PetscCall(PetscObjectTypeCompare((PetscObject)eps,type,&match));
171 675 : if (match) PetscFunctionReturn(PETSC_SUCCESS);
172 :
173 649 : PetscCall(PetscFunctionListFind(EPSList,type,&r));
174 649 : PetscCheck(r,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown EPS type given: %s",type);
175 :
176 649 : PetscTryTypeMethod(eps,destroy);
177 649 : PetscCall(PetscMemzero(eps->ops,sizeof(struct _EPSOps)));
178 :
179 649 : eps->state = EPS_STATE_INITIAL;
180 649 : PetscCall(PetscObjectChangeTypeName((PetscObject)eps,type));
181 649 : PetscCall((*r)(eps));
182 649 : PetscFunctionReturn(PETSC_SUCCESS);
183 : }
184 :
185 : /*@
186 : EPSGetType - Gets the EPS type as a string from the EPS object.
187 :
188 : Not Collective
189 :
190 : Input Parameter:
191 : . eps - the eigensolver context
192 :
193 : Output Parameter:
194 : . type - name of EPS method
195 :
196 : Level: intermediate
197 :
198 : .seealso: EPSSetType()
199 : @*/
200 106 : PetscErrorCode EPSGetType(EPS eps,EPSType *type)
201 : {
202 106 : PetscFunctionBegin;
203 106 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
204 106 : PetscAssertPointer(type,2);
205 106 : *type = ((PetscObject)eps)->type_name;
206 106 : PetscFunctionReturn(PETSC_SUCCESS);
207 : }
208 :
209 : /*@C
210 : EPSRegister - Adds a method to the eigenproblem solver package.
211 :
212 : Not Collective
213 :
214 : Input Parameters:
215 : + name - name of a new user-defined solver
216 : - function - routine to create the solver context
217 :
218 : Notes:
219 : EPSRegister() may be called multiple times to add several user-defined solvers.
220 :
221 : Example Usage:
222 : .vb
223 : EPSRegister("my_solver",MySolverCreate);
224 : .ve
225 :
226 : Then, your solver can be chosen with the procedural interface via
227 : $ EPSSetType(eps,"my_solver")
228 : or at runtime via the option
229 : $ -eps_type my_solver
230 :
231 : Level: advanced
232 :
233 : .seealso: EPSRegisterAll()
234 : @*/
235 10285 : PetscErrorCode EPSRegister(const char *name,PetscErrorCode (*function)(EPS))
236 : {
237 10285 : PetscFunctionBegin;
238 10285 : PetscCall(EPSInitializePackage());
239 10285 : PetscCall(PetscFunctionListAdd(&EPSList,name,function));
240 10285 : PetscFunctionReturn(PETSC_SUCCESS);
241 : }
242 :
243 : /*@C
244 : EPSMonitorRegister - Adds EPS monitor routine.
245 :
246 : Not Collective
247 :
248 : Input Parameters:
249 : + name - name of a new monitor routine
250 : . vtype - a PetscViewerType for the output
251 : . format - a PetscViewerFormat for the output
252 : . monitor - monitor routine
253 : . create - creation routine, or NULL
254 : - destroy - destruction routine, or NULL
255 :
256 : Notes:
257 : EPSMonitorRegister() may be called multiple times to add several user-defined monitors.
258 :
259 : Example Usage:
260 : .vb
261 : EPSMonitorRegister("my_monitor",PETSCVIEWERASCII,PETSC_VIEWER_ASCII_INFO_DETAIL,MyMonitor,NULL,NULL);
262 : .ve
263 :
264 : Then, your monitor can be chosen with the procedural interface via
265 : $ EPSMonitorSetFromOptions(eps,"-eps_monitor_my_monitor","my_monitor",NULL)
266 : or at runtime via the option
267 : $ -eps_monitor_my_monitor
268 :
269 : Level: advanced
270 :
271 : .seealso: EPSMonitorRegisterAll()
272 : @*/
273 3630 : PetscErrorCode EPSMonitorRegister(const char name[],PetscViewerType vtype,PetscViewerFormat format,PetscErrorCode (*monitor)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscErrorCode (*create)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**),PetscErrorCode (*destroy)(PetscViewerAndFormat**))
274 : {
275 3630 : char key[PETSC_MAX_PATH_LEN];
276 :
277 3630 : PetscFunctionBegin;
278 3630 : PetscCall(EPSInitializePackage());
279 3630 : PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
280 3630 : PetscCall(PetscFunctionListAdd(&EPSMonitorList,key,monitor));
281 3630 : if (create) PetscCall(PetscFunctionListAdd(&EPSMonitorCreateList,key,create));
282 3630 : if (destroy) PetscCall(PetscFunctionListAdd(&EPSMonitorDestroyList,key,destroy));
283 3630 : PetscFunctionReturn(PETSC_SUCCESS);
284 : }
285 :
286 : /*@
287 : EPSReset - Resets the EPS context to the initial state (prior to setup)
288 : and destroys any allocated Vecs and Mats.
289 :
290 : Collective
291 :
292 : Input Parameter:
293 : . eps - eigensolver context obtained from EPSCreate()
294 :
295 : Note:
296 : This can be used when a problem of different matrix size wants to be solved.
297 : All options that have previously been set are preserved, so in a next use
298 : the solver configuration is the same, but new sizes for matrices and vectors
299 : are allowed.
300 :
301 : Level: advanced
302 :
303 : .seealso: EPSDestroy()
304 : @*/
305 830 : PetscErrorCode EPSReset(EPS eps)
306 : {
307 830 : PetscFunctionBegin;
308 830 : if (eps) PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
309 830 : if (!eps) PetscFunctionReturn(PETSC_SUCCESS);
310 830 : PetscTryTypeMethod(eps,reset);
311 830 : if (eps->st) PetscCall(STReset(eps->st));
312 830 : PetscCall(VecDestroy(&eps->D));
313 830 : PetscCall(BVDestroy(&eps->V));
314 830 : PetscCall(BVDestroy(&eps->W));
315 830 : PetscCall(VecDestroyVecs(eps->nwork,&eps->work));
316 830 : eps->nwork = 0;
317 830 : eps->state = EPS_STATE_INITIAL;
318 830 : PetscFunctionReturn(PETSC_SUCCESS);
319 : }
320 :
321 : /*@
322 : EPSDestroy - Destroys the EPS context.
323 :
324 : Collective
325 :
326 : Input Parameter:
327 : . eps - eigensolver context obtained from EPSCreate()
328 :
329 : Level: beginner
330 :
331 : .seealso: EPSCreate(), EPSSetUp(), EPSSolve()
332 : @*/
333 723 : PetscErrorCode EPSDestroy(EPS *eps)
334 : {
335 723 : PetscFunctionBegin;
336 723 : if (!*eps) PetscFunctionReturn(PETSC_SUCCESS);
337 689 : PetscValidHeaderSpecific(*eps,EPS_CLASSID,1);
338 689 : if (--((PetscObject)*eps)->refct > 0) { *eps = NULL; PetscFunctionReturn(PETSC_SUCCESS); }
339 648 : PetscCall(EPSReset(*eps));
340 648 : PetscTryTypeMethod(*eps,destroy);
341 648 : if ((*eps)->eigr) PetscCall(PetscFree4((*eps)->eigr,(*eps)->eigi,(*eps)->errest,(*eps)->perm));
342 648 : if ((*eps)->rr) PetscCall(PetscFree2((*eps)->rr,(*eps)->ri));
343 648 : PetscCall(STDestroy(&(*eps)->st));
344 648 : PetscCall(RGDestroy(&(*eps)->rg));
345 648 : PetscCall(DSDestroy(&(*eps)->ds));
346 648 : PetscCall(PetscFree((*eps)->sc));
347 : /* just in case the initial vectors have not been used */
348 648 : PetscCall(SlepcBasisDestroy_Private(&(*eps)->nds,&(*eps)->defl));
349 648 : PetscCall(SlepcBasisDestroy_Private(&(*eps)->nini,&(*eps)->IS));
350 648 : PetscCall(SlepcBasisDestroy_Private(&(*eps)->ninil,&(*eps)->ISL));
351 648 : if ((*eps)->convergeddestroy) PetscCall((*(*eps)->convergeddestroy)(&(*eps)->convergedctx));
352 648 : if ((*eps)->stoppingdestroy) PetscCall((*(*eps)->stoppingdestroy)(&(*eps)->stoppingctx));
353 648 : PetscCall(EPSMonitorCancel(*eps));
354 648 : PetscCall(PetscHeaderDestroy(eps));
355 648 : PetscFunctionReturn(PETSC_SUCCESS);
356 : }
357 :
358 : /*@
359 : EPSSetTarget - Sets the value of the target.
360 :
361 : Logically Collective
362 :
363 : Input Parameters:
364 : + eps - eigensolver context
365 : - target - the value of the target
366 :
367 : Options Database Key:
368 : . -eps_target <scalar> - the value of the target
369 :
370 : Notes:
371 : The target is a scalar value used to determine the portion of the spectrum
372 : of interest. It is used in combination with EPSSetWhichEigenpairs().
373 :
374 : In the case of complex scalars, a complex value can be provided in the
375 : command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
376 : -eps_target 1.0+2.0i
377 :
378 : Level: intermediate
379 :
380 : .seealso: EPSGetTarget(), EPSSetWhichEigenpairs()
381 : @*/
382 164 : PetscErrorCode EPSSetTarget(EPS eps,PetscScalar target)
383 : {
384 164 : PetscFunctionBegin;
385 164 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
386 492 : PetscValidLogicalCollectiveScalar(eps,target,2);
387 164 : eps->target = target;
388 164 : if (!eps->st) PetscCall(EPSGetST(eps,&eps->st));
389 164 : PetscCall(STSetDefaultShift(eps->st,target));
390 164 : PetscFunctionReturn(PETSC_SUCCESS);
391 : }
392 :
393 : /*@
394 : EPSGetTarget - Gets the value of the target.
395 :
396 : Not Collective
397 :
398 : Input Parameter:
399 : . eps - eigensolver context
400 :
401 : Output Parameter:
402 : . target - the value of the target
403 :
404 : Note:
405 : If the target was not set by the user, then zero is returned.
406 :
407 : Level: intermediate
408 :
409 : .seealso: EPSSetTarget()
410 : @*/
411 1321 : PetscErrorCode EPSGetTarget(EPS eps,PetscScalar* target)
412 : {
413 1321 : PetscFunctionBegin;
414 1321 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
415 1321 : PetscAssertPointer(target,2);
416 1321 : *target = eps->target;
417 1321 : PetscFunctionReturn(PETSC_SUCCESS);
418 : }
419 :
420 : /*@
421 : EPSSetInterval - Defines the computational interval for spectrum slicing.
422 :
423 : Logically Collective
424 :
425 : Input Parameters:
426 : + eps - eigensolver context
427 : . inta - left end of the interval
428 : - intb - right end of the interval
429 :
430 : Options Database Key:
431 : . -eps_interval <a,b> - set [a,b] as the interval of interest
432 :
433 : Notes:
434 : Spectrum slicing is a technique employed for computing all eigenvalues of
435 : symmetric eigenproblems in a given interval. This function provides the
436 : interval to be considered. It must be used in combination with EPS_ALL, see
437 : EPSSetWhichEigenpairs().
438 :
439 : In the command-line option, two values must be provided. For an open interval,
440 : one can give an infinite, e.g., -eps_interval 1.0,inf or -eps_interval -inf,1.0.
441 : An open interval in the programmatic interface can be specified with
442 : PETSC_MAX_REAL and -PETSC_MAX_REAL.
443 :
444 : Level: intermediate
445 :
446 : .seealso: EPSGetInterval(), EPSSetWhichEigenpairs()
447 : @*/
448 48 : PetscErrorCode EPSSetInterval(EPS eps,PetscReal inta,PetscReal intb)
449 : {
450 48 : PetscFunctionBegin;
451 48 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
452 144 : PetscValidLogicalCollectiveReal(eps,inta,2);
453 144 : PetscValidLogicalCollectiveReal(eps,intb,3);
454 48 : PetscCheck(inta<intb,PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Badly defined interval, must be inta<intb");
455 48 : if (eps->inta != inta || eps->intb != intb) {
456 45 : eps->inta = inta;
457 45 : eps->intb = intb;
458 45 : eps->state = EPS_STATE_INITIAL;
459 : }
460 48 : PetscFunctionReturn(PETSC_SUCCESS);
461 : }
462 :
463 : /*@
464 : EPSGetInterval - Gets the computational interval for spectrum slicing.
465 :
466 : Not Collective
467 :
468 : Input Parameter:
469 : . eps - eigensolver context
470 :
471 : Output Parameters:
472 : + inta - left end of the interval
473 : - intb - right end of the interval
474 :
475 : Level: intermediate
476 :
477 : Note:
478 : If the interval was not set by the user, then zeros are returned.
479 :
480 : .seealso: EPSSetInterval()
481 : @*/
482 10 : PetscErrorCode EPSGetInterval(EPS eps,PetscReal* inta,PetscReal* intb)
483 : {
484 10 : PetscFunctionBegin;
485 10 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
486 10 : if (inta) *inta = eps->inta;
487 10 : if (intb) *intb = eps->intb;
488 10 : PetscFunctionReturn(PETSC_SUCCESS);
489 : }
490 :
491 : /*@
492 : EPSSetST - Associates a spectral transformation object to the eigensolver.
493 :
494 : Collective
495 :
496 : Input Parameters:
497 : + eps - eigensolver context obtained from EPSCreate()
498 : - st - the spectral transformation object
499 :
500 : Note:
501 : Use EPSGetST() to retrieve the spectral transformation context (for example,
502 : to free it at the end of the computations).
503 :
504 : Level: advanced
505 :
506 : .seealso: EPSGetST()
507 : @*/
508 1 : PetscErrorCode EPSSetST(EPS eps,ST st)
509 : {
510 1 : PetscFunctionBegin;
511 1 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
512 1 : PetscValidHeaderSpecific(st,ST_CLASSID,2);
513 1 : PetscCheckSameComm(eps,1,st,2);
514 1 : PetscCall(PetscObjectReference((PetscObject)st));
515 1 : PetscCall(STDestroy(&eps->st));
516 1 : eps->st = st;
517 1 : PetscFunctionReturn(PETSC_SUCCESS);
518 : }
519 :
520 : /*@
521 : EPSGetST - Obtain the spectral transformation (ST) object associated
522 : to the eigensolver object.
523 :
524 : Not Collective
525 :
526 : Input Parameters:
527 : . eps - eigensolver context obtained from EPSCreate()
528 :
529 : Output Parameter:
530 : . st - spectral transformation context
531 :
532 : Level: intermediate
533 :
534 : .seealso: EPSSetST()
535 : @*/
536 6337 : PetscErrorCode EPSGetST(EPS eps,ST *st)
537 : {
538 6337 : PetscFunctionBegin;
539 6337 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
540 6337 : PetscAssertPointer(st,2);
541 6337 : if (!eps->st) {
542 647 : PetscCall(STCreate(PetscObjectComm((PetscObject)eps),&eps->st));
543 647 : PetscCall(PetscObjectIncrementTabLevel((PetscObject)eps->st,(PetscObject)eps,0));
544 647 : PetscCall(PetscObjectSetOptions((PetscObject)eps->st,((PetscObject)eps)->options));
545 : }
546 6337 : *st = eps->st;
547 6337 : PetscFunctionReturn(PETSC_SUCCESS);
548 : }
549 :
550 : /*@
551 : EPSSetBV - Associates a basis vectors object to the eigensolver.
552 :
553 : Collective
554 :
555 : Input Parameters:
556 : + eps - eigensolver context obtained from EPSCreate()
557 : - V - the basis vectors object
558 :
559 : Level: advanced
560 :
561 : .seealso: EPSGetBV()
562 : @*/
563 0 : PetscErrorCode EPSSetBV(EPS eps,BV V)
564 : {
565 0 : PetscFunctionBegin;
566 0 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
567 0 : PetscValidHeaderSpecific(V,BV_CLASSID,2);
568 0 : PetscCheckSameComm(eps,1,V,2);
569 0 : PetscCall(PetscObjectReference((PetscObject)V));
570 0 : PetscCall(BVDestroy(&eps->V));
571 0 : eps->V = V;
572 0 : PetscFunctionReturn(PETSC_SUCCESS);
573 : }
574 :
575 : /*@
576 : EPSGetBV - Obtain the basis vectors object associated to the eigensolver object.
577 :
578 : Not Collective
579 :
580 : Input Parameters:
581 : . eps - eigensolver context obtained from EPSCreate()
582 :
583 : Output Parameter:
584 : . V - basis vectors context
585 :
586 : Level: advanced
587 :
588 : .seealso: EPSSetBV()
589 : @*/
590 701 : PetscErrorCode EPSGetBV(EPS eps,BV *V)
591 : {
592 701 : PetscFunctionBegin;
593 701 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
594 701 : PetscAssertPointer(V,2);
595 701 : if (!eps->V) {
596 682 : PetscCall(BVCreate(PetscObjectComm((PetscObject)eps),&eps->V));
597 682 : PetscCall(PetscObjectIncrementTabLevel((PetscObject)eps->V,(PetscObject)eps,0));
598 682 : PetscCall(PetscObjectSetOptions((PetscObject)eps->V,((PetscObject)eps)->options));
599 : }
600 701 : *V = eps->V;
601 701 : PetscFunctionReturn(PETSC_SUCCESS);
602 : }
603 :
604 : /*@
605 : EPSSetRG - Associates a region object to the eigensolver.
606 :
607 : Collective
608 :
609 : Input Parameters:
610 : + eps - eigensolver context obtained from EPSCreate()
611 : - rg - the region object
612 :
613 : Note:
614 : Use EPSGetRG() to retrieve the region context (for example,
615 : to free it at the end of the computations).
616 :
617 : Level: advanced
618 :
619 : .seealso: EPSGetRG()
620 : @*/
621 5 : PetscErrorCode EPSSetRG(EPS eps,RG rg)
622 : {
623 5 : PetscFunctionBegin;
624 5 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
625 5 : if (rg) {
626 5 : PetscValidHeaderSpecific(rg,RG_CLASSID,2);
627 5 : PetscCheckSameComm(eps,1,rg,2);
628 : }
629 5 : PetscCall(PetscObjectReference((PetscObject)rg));
630 5 : PetscCall(RGDestroy(&eps->rg));
631 5 : eps->rg = rg;
632 5 : PetscFunctionReturn(PETSC_SUCCESS);
633 : }
634 :
635 : /*@
636 : EPSGetRG - Obtain the region object associated to the eigensolver.
637 :
638 : Not Collective
639 :
640 : Input Parameters:
641 : . eps - eigensolver context obtained from EPSCreate()
642 :
643 : Output Parameter:
644 : . rg - region context
645 :
646 : Level: advanced
647 :
648 : .seealso: EPSSetRG()
649 : @*/
650 647 : PetscErrorCode EPSGetRG(EPS eps,RG *rg)
651 : {
652 647 : PetscFunctionBegin;
653 647 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
654 647 : PetscAssertPointer(rg,2);
655 647 : if (!eps->rg) {
656 647 : PetscCall(RGCreate(PetscObjectComm((PetscObject)eps),&eps->rg));
657 647 : PetscCall(PetscObjectIncrementTabLevel((PetscObject)eps->rg,(PetscObject)eps,0));
658 647 : PetscCall(PetscObjectSetOptions((PetscObject)eps->rg,((PetscObject)eps)->options));
659 : }
660 647 : *rg = eps->rg;
661 647 : PetscFunctionReturn(PETSC_SUCCESS);
662 : }
663 :
664 : /*@
665 : EPSSetDS - Associates a direct solver object to the eigensolver.
666 :
667 : Collective
668 :
669 : Input Parameters:
670 : + eps - eigensolver context obtained from EPSCreate()
671 : - ds - the direct solver object
672 :
673 : Note:
674 : Use EPSGetDS() to retrieve the direct solver context (for example,
675 : to free it at the end of the computations).
676 :
677 : Level: advanced
678 :
679 : .seealso: EPSGetDS()
680 : @*/
681 0 : PetscErrorCode EPSSetDS(EPS eps,DS ds)
682 : {
683 0 : PetscFunctionBegin;
684 0 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
685 0 : PetscValidHeaderSpecific(ds,DS_CLASSID,2);
686 0 : PetscCheckSameComm(eps,1,ds,2);
687 0 : PetscCall(PetscObjectReference((PetscObject)ds));
688 0 : PetscCall(DSDestroy(&eps->ds));
689 0 : eps->ds = ds;
690 0 : PetscFunctionReturn(PETSC_SUCCESS);
691 : }
692 :
693 : /*@
694 : EPSGetDS - Obtain the direct solver object associated to the eigensolver object.
695 :
696 : Not Collective
697 :
698 : Input Parameters:
699 : . eps - eigensolver context obtained from EPSCreate()
700 :
701 : Output Parameter:
702 : . ds - direct solver context
703 :
704 : Level: advanced
705 :
706 : .seealso: EPSSetDS()
707 : @*/
708 593 : PetscErrorCode EPSGetDS(EPS eps,DS *ds)
709 : {
710 593 : PetscFunctionBegin;
711 593 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
712 593 : PetscAssertPointer(ds,2);
713 593 : if (!eps->ds) {
714 593 : PetscCall(DSCreate(PetscObjectComm((PetscObject)eps),&eps->ds));
715 593 : PetscCall(PetscObjectIncrementTabLevel((PetscObject)eps->ds,(PetscObject)eps,0));
716 593 : PetscCall(PetscObjectSetOptions((PetscObject)eps->ds,((PetscObject)eps)->options));
717 : }
718 593 : *ds = eps->ds;
719 593 : PetscFunctionReturn(PETSC_SUCCESS);
720 : }
721 :
722 : /*@
723 : EPSIsGeneralized - Ask if the EPS object corresponds to a generalized
724 : eigenvalue problem.
725 :
726 : Not Collective
727 :
728 : Input Parameter:
729 : . eps - the eigenproblem solver context
730 :
731 : Output Parameter:
732 : . is - the answer
733 :
734 : Level: intermediate
735 :
736 : .seealso: EPSIsHermitian(), EPSIsPositive(), EPSIsStructured()
737 : @*/
738 1 : PetscErrorCode EPSIsGeneralized(EPS eps,PetscBool* is)
739 : {
740 1 : PetscFunctionBegin;
741 1 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
742 1 : PetscAssertPointer(is,2);
743 1 : *is = eps->isgeneralized;
744 1 : PetscFunctionReturn(PETSC_SUCCESS);
745 : }
746 :
747 : /*@
748 : EPSIsHermitian - Ask if the EPS object corresponds to a Hermitian
749 : eigenvalue problem.
750 :
751 : Not Collective
752 :
753 : Input Parameter:
754 : . eps - the eigenproblem solver context
755 :
756 : Output Parameter:
757 : . is - the answer
758 :
759 : Level: intermediate
760 :
761 : .seealso: EPSIsGeneralized(), EPSIsPositive(), EPSIsStructured()
762 : @*/
763 1 : PetscErrorCode EPSIsHermitian(EPS eps,PetscBool* is)
764 : {
765 1 : PetscFunctionBegin;
766 1 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
767 1 : PetscAssertPointer(is,2);
768 1 : *is = eps->ishermitian;
769 1 : PetscFunctionReturn(PETSC_SUCCESS);
770 : }
771 :
772 : /*@
773 : EPSIsPositive - Ask if the EPS object corresponds to an eigenvalue
774 : problem type that requires a positive (semi-) definite matrix B.
775 :
776 : Not Collective
777 :
778 : Input Parameter:
779 : . eps - the eigenproblem solver context
780 :
781 : Output Parameter:
782 : . is - the answer
783 :
784 : Level: intermediate
785 :
786 : .seealso: EPSIsGeneralized(), EPSIsHermitian(), EPSIsStructured()
787 : @*/
788 1 : PetscErrorCode EPSIsPositive(EPS eps,PetscBool* is)
789 : {
790 1 : PetscFunctionBegin;
791 1 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
792 1 : PetscAssertPointer(is,2);
793 1 : *is = eps->ispositive;
794 1 : PetscFunctionReturn(PETSC_SUCCESS);
795 : }
796 :
797 : /*@
798 : EPSIsStructured - Ask if the EPS object corresponds to a structured
799 : eigenvalue problem.
800 :
801 : Not Collective
802 :
803 : Input Parameter:
804 : . eps - the eigenproblem solver context
805 :
806 : Output Parameter:
807 : . is - the answer
808 :
809 : Note:
810 : The result will be true if the problem type has been set to some
811 : structured type such as EPS_BSE. This is independent of whether the
812 : input matrix has been built with a certain structure with a helper function.
813 :
814 : Level: intermediate
815 :
816 : .seealso: EPSIsGeneralized(), EPSIsHermitian(), EPSIsPositive(), EPSSetProblemType()
817 : @*/
818 0 : PetscErrorCode EPSIsStructured(EPS eps,PetscBool* is)
819 : {
820 0 : PetscFunctionBegin;
821 0 : PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
822 0 : PetscAssertPointer(is,2);
823 0 : *is = eps->isstructured;
824 0 : PetscFunctionReturn(PETSC_SUCCESS);
825 : }
|
