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