Actual source code: pepbasic.c

  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

  6:    This file is part of SLEPc.
  7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
  8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  9: */
 10: /*
 11:    Basic PEP routines
 12: */

 14: #include <slepc/private/pepimpl.h>

 16: /* Logging support */
 17: PetscClassId      PEP_CLASSID = 0;
 18: PetscLogEvent     PEP_SetUp = 0,PEP_Solve = 0,PEP_Refine = 0,PEP_CISS_SVD = 0;

 20: /* List of registered PEP routines */
 21: PetscFunctionList PEPList = NULL;
 22: PetscBool         PEPRegisterAllCalled = PETSC_FALSE;

 24: /* List of registered PEP monitors */
 25: PetscFunctionList PEPMonitorList              = NULL;
 26: PetscFunctionList PEPMonitorCreateList        = NULL;
 27: PetscFunctionList PEPMonitorDestroyList       = NULL;
 28: PetscBool         PEPMonitorRegisterAllCalled = PETSC_FALSE;

 30: /*@
 31:    PEPCreate - Creates the default PEP context.

 33:    Collective

 35:    Input Parameter:
 36: .  comm - MPI communicator

 38:    Output Parameter:
 39: .  outpep - location to put the PEP context

 41:    Note:
 42:    The default PEP type is PEPTOAR

 44:    Level: beginner

 46: .seealso: `PEPSetUp()`, `PEPSolve()`, `PEPDestroy()`, `PEP`
 47: @*/
 48: PetscErrorCode PEPCreate(MPI_Comm comm,PEP *outpep)
 49: {
 50:   PEP            pep;

 52:   PetscFunctionBegin;
 53:   PetscAssertPointer(outpep,2);
 54:   PetscCall(PEPInitializePackage());
 55:   PetscCall(SlepcHeaderCreate(pep,PEP_CLASSID,"PEP","Polynomial Eigenvalue Problem","PEP",comm,PEPDestroy,PEPView));

 57:   pep->max_it          = PETSC_DETERMINE;
 58:   pep->nev             = 1;
 59:   pep->ncv             = PETSC_DETERMINE;
 60:   pep->mpd             = PETSC_DETERMINE;
 61:   pep->nini            = 0;
 62:   pep->target          = 0.0;
 63:   pep->tol             = PETSC_DETERMINE;
 64:   pep->conv            = PEP_CONV_REL;
 65:   pep->stop            = PEP_STOP_BASIC;
 66:   pep->which           = (PEPWhich)0;
 67:   pep->basis           = PEP_BASIS_MONOMIAL;
 68:   pep->problem_type    = (PEPProblemType)0;
 69:   pep->scale           = PEP_SCALE_NONE;
 70:   pep->sfactor         = 1.0;
 71:   pep->dsfactor        = 1.0;
 72:   pep->sits            = 5;
 73:   pep->slambda         = 1.0;
 74:   pep->refine          = PEP_REFINE_NONE;
 75:   pep->npart           = 1;
 76:   pep->rtol            = PETSC_DETERMINE;
 77:   pep->rits            = PETSC_DETERMINE;
 78:   pep->scheme          = (PEPRefineScheme)0;
 79:   pep->extract         = (PEPExtract)0;
 80:   pep->trackall        = PETSC_FALSE;

 82:   pep->converged       = PEPConvergedRelative;
 83:   pep->convergeduser   = NULL;
 84:   pep->convergeddestroy= NULL;
 85:   pep->stopping        = PEPStoppingBasic;
 86:   pep->stoppinguser    = NULL;
 87:   pep->stoppingdestroy = NULL;
 88:   pep->convergedctx    = NULL;
 89:   pep->stoppingctx     = NULL;
 90:   pep->numbermonitors  = 0;

 92:   pep->st              = NULL;
 93:   pep->ds              = NULL;
 94:   pep->V               = NULL;
 95:   pep->rg              = NULL;
 96:   pep->A               = NULL;
 97:   pep->nmat            = 0;
 98:   pep->Dl              = NULL;
 99:   pep->Dr              = NULL;
100:   pep->IS              = NULL;
101:   pep->eigr            = NULL;
102:   pep->eigi            = NULL;
103:   pep->errest          = NULL;
104:   pep->perm            = NULL;
105:   pep->pbc             = NULL;
106:   pep->solvematcoeffs  = NULL;
107:   pep->nwork           = 0;
108:   pep->work            = NULL;
109:   pep->refineksp       = NULL;
110:   pep->refinesubc      = NULL;
111:   pep->data            = NULL;

113:   pep->state           = PEP_STATE_INITIAL;
114:   pep->nconv           = 0;
115:   pep->its             = 0;
116:   pep->n               = 0;
117:   pep->nloc            = 0;
118:   pep->nrma            = NULL;
119:   pep->sfactor_set     = PETSC_FALSE;
120:   pep->lineariz        = PETSC_FALSE;
121:   pep->reason          = PEP_CONVERGED_ITERATING;

123:   PetscCall(PetscNew(&pep->sc));
124:   *outpep = pep;
125:   PetscFunctionReturn(PETSC_SUCCESS);
126: }

128: /*@
129:    PEPSetType - Selects the particular solver to be used in the PEP object.

131:    Logically Collective

133:    Input Parameters:
134: +  pep      - the polynomial eigensolver context
135: -  type     - a known method

137:    Options Database Key:
138: .  -pep_type <method> - Sets the method; use -help for a list
139:     of available methods

141:    Notes:
142:    See "slepc/include/slepcpep.h" for available methods. The default
143:    is PEPTOAR.

145:    Normally, it is best to use the PEPSetFromOptions() command and
146:    then set the PEP type from the options database rather than by using
147:    this routine.  Using the options database provides the user with
148:    maximum flexibility in evaluating the different available methods.
149:    The PEPSetType() routine is provided for those situations where it
150:    is necessary to set the iterative solver independently of the command
151:    line or options database.

153:    Level: intermediate

155: .seealso: `PEPType`
156: @*/
157: PetscErrorCode PEPSetType(PEP pep,PEPType type)
158: {
159:   PetscErrorCode (*r)(PEP);
160:   PetscBool      match;

162:   PetscFunctionBegin;
164:   PetscAssertPointer(type,2);

166:   PetscCall(PetscObjectTypeCompare((PetscObject)pep,type,&match));
167:   if (match) PetscFunctionReturn(PETSC_SUCCESS);

169:   PetscCall(PetscFunctionListFind(PEPList,type,&r));
170:   PetscCheck(r,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown PEP type given: %s",type);

172:   PetscTryTypeMethod(pep,destroy);
173:   PetscCall(PetscMemzero(pep->ops,sizeof(struct _PEPOps)));

175:   pep->state = PEP_STATE_INITIAL;
176:   PetscCall(PetscObjectChangeTypeName((PetscObject)pep,type));
177:   PetscCall((*r)(pep));
178:   PetscFunctionReturn(PETSC_SUCCESS);
179: }

181: /*@
182:    PEPGetType - Gets the PEP type as a string from the PEP object.

184:    Not Collective

186:    Input Parameter:
187: .  pep - the eigensolver context

189:    Output Parameter:
190: .  type - name of PEP method

192:    Level: intermediate

194: .seealso: `PEPSetType()`
195: @*/
196: PetscErrorCode PEPGetType(PEP pep,PEPType *type)
197: {
198:   PetscFunctionBegin;
200:   PetscAssertPointer(type,2);
201:   *type = ((PetscObject)pep)->type_name;
202:   PetscFunctionReturn(PETSC_SUCCESS);
203: }

205: /*@C
206:    PEPRegister - Adds a method to the polynomial eigenproblem solver package.

208:    Not Collective

210:    Input Parameters:
211: +  name - name of a new user-defined solver
212: -  function - routine to create the solver context

214:    Notes:
215:    PEPRegister() may be called multiple times to add several user-defined solvers.

217:    Example Usage:
218: .vb
219:     PEPRegister("my_solver",MySolverCreate);
220: .ve

222:    Then, your solver can be chosen with the procedural interface via
223: $     PEPSetType(pep,"my_solver")
224:    or at runtime via the option
225: $     -pep_type my_solver

227:    Level: advanced

229: .seealso: `PEPRegisterAll()`
230: @*/
231: PetscErrorCode PEPRegister(const char *name,PetscErrorCode (*function)(PEP))
232: {
233:   PetscFunctionBegin;
234:   PetscCall(PEPInitializePackage());
235:   PetscCall(PetscFunctionListAdd(&PEPList,name,function));
236:   PetscFunctionReturn(PETSC_SUCCESS);
237: }

239: /*@C
240:    PEPMonitorRegister - Registers a PEP monitor routine that may be accessed with PEPMonitorSetFromOptions().

242:    Not Collective

244:    Input Parameters:
245: +  name    - name of a new monitor routine
246: .  vtype   - a PetscViewerType for the output
247: .  format  - a PetscViewerFormat for the output
248: .  monitor - monitor routine, see PEPMonitorRegisterFn
249: .  create  - creation routine, or NULL
250: -  destroy - destruction routine, or NULL

252:    Notes:
253:    PEPMonitorRegister() may be called multiple times to add several user-defined monitors.

255:    The calling sequence for the given function matches the calling sequence of PEPMonitorFn
256:    functions passed to PEPMonitorSet() with the additional requirement that its final argument
257:    be a PetscViewerAndFormat.

259:    Example Usage:
260: .vb
261:    PEPMonitorRegister("my_monitor",PETSCVIEWERASCII,PETSC_VIEWER_ASCII_INFO_DETAIL,MyMonitor,NULL,NULL);
262: .ve

264:    Then, your monitor can be chosen with the procedural interface via
265: $      PEPMonitorSetFromOptions(pep,"-pep_monitor_my_monitor","my_monitor",NULL)
266:    or at runtime via the option
267: $      -pep_monitor_my_monitor

269:    Level: advanced

271: .seealso: `PEPMonitorSet()`, `PEPMonitorRegisterAll()`
272: @*/
273: PetscErrorCode PEPMonitorRegister(const char name[],PetscViewerType vtype,PetscViewerFormat format,PEPMonitorRegisterFn *monitor,PEPMonitorRegisterCreateFn *create,PEPMonitorRegisterDestroyFn *destroy)
274: {
275:   char           key[PETSC_MAX_PATH_LEN];

277:   PetscFunctionBegin;
278:   PetscCall(PEPInitializePackage());
279:   PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
280:   PetscCall(PetscFunctionListAdd(&PEPMonitorList,key,monitor));
281:   if (create)  PetscCall(PetscFunctionListAdd(&PEPMonitorCreateList,key,create));
282:   if (destroy) PetscCall(PetscFunctionListAdd(&PEPMonitorDestroyList,key,destroy));
283:   PetscFunctionReturn(PETSC_SUCCESS);
284: }

286: /*@
287:    PEPReset - Resets the PEP context to the initial state (prior to setup)
288:    and destroys any allocated Vecs and Mats.

290:    Collective

292:    Input Parameter:
293: .  pep - eigensolver context obtained from PEPCreate()

295:    Level: advanced

297: .seealso: `PEPDestroy()`
298: @*/
299: PetscErrorCode PEPReset(PEP pep)
300: {
301:   PetscFunctionBegin;
303:   if (!pep) PetscFunctionReturn(PETSC_SUCCESS);
304:   PetscTryTypeMethod(pep,reset);
305:   if (pep->st) PetscCall(STReset(pep->st));
306:   if (pep->refineksp) PetscCall(KSPReset(pep->refineksp));
307:   if (pep->nmat) {
308:     PetscCall(MatDestroyMatrices(pep->nmat,&pep->A));
309:     PetscCall(PetscFree2(pep->pbc,pep->nrma));
310:     PetscCall(PetscFree(pep->solvematcoeffs));
311:     pep->nmat = 0;
312:   }
313:   PetscCall(VecDestroy(&pep->Dl));
314:   PetscCall(VecDestroy(&pep->Dr));
315:   PetscCall(BVDestroy(&pep->V));
316:   PetscCall(VecDestroyVecs(pep->nwork,&pep->work));
317:   pep->nwork = 0;
318:   pep->state = PEP_STATE_INITIAL;
319:   PetscFunctionReturn(PETSC_SUCCESS);
320: }

322: /*@
323:    PEPDestroy - Destroys the PEP context.

325:    Collective

327:    Input Parameter:
328: .  pep - eigensolver context obtained from PEPCreate()

330:    Level: beginner

332: .seealso: `PEPCreate()`, `PEPSetUp()`, `PEPSolve()`
333: @*/
334: PetscErrorCode PEPDestroy(PEP *pep)
335: {
336:   PetscFunctionBegin;
337:   if (!*pep) PetscFunctionReturn(PETSC_SUCCESS);
339:   if (--((PetscObject)*pep)->refct > 0) { *pep = NULL; PetscFunctionReturn(PETSC_SUCCESS); }
340:   PetscCall(PEPReset(*pep));
341:   PetscTryTypeMethod(*pep,destroy);
342:   if ((*pep)->eigr) PetscCall(PetscFree4((*pep)->eigr,(*pep)->eigi,(*pep)->errest,(*pep)->perm));
343:   PetscCall(STDestroy(&(*pep)->st));
344:   PetscCall(RGDestroy(&(*pep)->rg));
345:   PetscCall(DSDestroy(&(*pep)->ds));
346:   PetscCall(KSPDestroy(&(*pep)->refineksp));
347:   PetscCall(PetscSubcommDestroy(&(*pep)->refinesubc));
348:   PetscCall(PetscFree((*pep)->sc));
349:   /* just in case the initial vectors have not been used */
350:   PetscCall(SlepcBasisDestroy_Private(&(*pep)->nini,&(*pep)->IS));
351:   if ((*pep)->convergeddestroy) PetscCall((*(*pep)->convergeddestroy)(&(*pep)->convergedctx));
352:   if ((*pep)->stoppingdestroy) PetscCall((*(*pep)->stoppingdestroy)(&(*pep)->stoppingctx));
353:   PetscCall(PEPMonitorCancel(*pep));
354:   PetscCall(PetscHeaderDestroy(pep));
355:   PetscFunctionReturn(PETSC_SUCCESS);
356: }

358: /*@
359:    PEPSetBV - Associates a basis vectors object to the polynomial eigensolver.

361:    Collective

363:    Input Parameters:
364: +  pep - eigensolver context obtained from PEPCreate()
365: -  bv  - the basis vectors object

367:    Note:
368:    Use PEPGetBV() to retrieve the basis vectors context (for example,
369:    to free it at the end of the computations).

371:    Level: advanced

373: .seealso: `PEPGetBV()`
374: @*/
375: PetscErrorCode PEPSetBV(PEP pep,BV bv)
376: {
377:   PetscFunctionBegin;
380:   PetscCheckSameComm(pep,1,bv,2);
381:   PetscCall(PetscObjectReference((PetscObject)bv));
382:   PetscCall(BVDestroy(&pep->V));
383:   pep->V = bv;
384:   PetscFunctionReturn(PETSC_SUCCESS);
385: }

387: /*@
388:    PEPGetBV - Obtain the basis vectors object associated to the polynomial
389:    eigensolver object.

391:    Not Collective

393:    Input Parameters:
394: .  pep - eigensolver context obtained from PEPCreate()

396:    Output Parameter:
397: .  bv - basis vectors context

399:    Level: advanced

401: .seealso: `PEPSetBV()`
402: @*/
403: PetscErrorCode PEPGetBV(PEP pep,BV *bv)
404: {
405:   PetscFunctionBegin;
407:   PetscAssertPointer(bv,2);
408:   if (!pep->V) {
409:     PetscCall(BVCreate(PetscObjectComm((PetscObject)pep),&pep->V));
410:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)pep->V,(PetscObject)pep,0));
411:     PetscCall(PetscObjectSetOptions((PetscObject)pep->V,((PetscObject)pep)->options));
412:   }
413:   *bv = pep->V;
414:   PetscFunctionReturn(PETSC_SUCCESS);
415: }

417: /*@
418:    PEPSetRG - Associates a region object to the polynomial eigensolver.

420:    Collective

422:    Input Parameters:
423: +  pep - eigensolver context obtained from PEPCreate()
424: -  rg  - the region object

426:    Note:
427:    Use PEPGetRG() to retrieve the region context (for example,
428:    to free it at the end of the computations).

430:    Level: advanced

432: .seealso: `PEPGetRG()`
433: @*/
434: PetscErrorCode PEPSetRG(PEP pep,RG rg)
435: {
436:   PetscFunctionBegin;
438:   if (rg) {
440:     PetscCheckSameComm(pep,1,rg,2);
441:   }
442:   PetscCall(PetscObjectReference((PetscObject)rg));
443:   PetscCall(RGDestroy(&pep->rg));
444:   pep->rg = rg;
445:   PetscFunctionReturn(PETSC_SUCCESS);
446: }

448: /*@
449:    PEPGetRG - Obtain the region object associated to the
450:    polynomial eigensolver object.

452:    Not Collective

454:    Input Parameters:
455: .  pep - eigensolver context obtained from PEPCreate()

457:    Output Parameter:
458: .  rg - region context

460:    Level: advanced

462: .seealso: `PEPSetRG()`
463: @*/
464: PetscErrorCode PEPGetRG(PEP pep,RG *rg)
465: {
466:   PetscFunctionBegin;
468:   PetscAssertPointer(rg,2);
469:   if (!pep->rg) {
470:     PetscCall(RGCreate(PetscObjectComm((PetscObject)pep),&pep->rg));
471:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)pep->rg,(PetscObject)pep,0));
472:     PetscCall(PetscObjectSetOptions((PetscObject)pep->rg,((PetscObject)pep)->options));
473:   }
474:   *rg = pep->rg;
475:   PetscFunctionReturn(PETSC_SUCCESS);
476: }

478: /*@
479:    PEPSetDS - Associates a direct solver object to the polynomial eigensolver.

481:    Collective

483:    Input Parameters:
484: +  pep - eigensolver context obtained from PEPCreate()
485: -  ds  - the direct solver object

487:    Note:
488:    Use PEPGetDS() to retrieve the direct solver context (for example,
489:    to free it at the end of the computations).

491:    Level: advanced

493: .seealso: `PEPGetDS()`
494: @*/
495: PetscErrorCode PEPSetDS(PEP pep,DS ds)
496: {
497:   PetscFunctionBegin;
500:   PetscCheckSameComm(pep,1,ds,2);
501:   PetscCall(PetscObjectReference((PetscObject)ds));
502:   PetscCall(DSDestroy(&pep->ds));
503:   pep->ds = ds;
504:   PetscFunctionReturn(PETSC_SUCCESS);
505: }

507: /*@
508:    PEPGetDS - Obtain the direct solver object associated to the
509:    polynomial eigensolver object.

511:    Not Collective

513:    Input Parameters:
514: .  pep - eigensolver context obtained from PEPCreate()

516:    Output Parameter:
517: .  ds - direct solver context

519:    Level: advanced

521: .seealso: `PEPSetDS()`
522: @*/
523: PetscErrorCode PEPGetDS(PEP pep,DS *ds)
524: {
525:   PetscFunctionBegin;
527:   PetscAssertPointer(ds,2);
528:   if (!pep->ds) {
529:     PetscCall(DSCreate(PetscObjectComm((PetscObject)pep),&pep->ds));
530:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)pep->ds,(PetscObject)pep,0));
531:     PetscCall(PetscObjectSetOptions((PetscObject)pep->ds,((PetscObject)pep)->options));
532:   }
533:   *ds = pep->ds;
534:   PetscFunctionReturn(PETSC_SUCCESS);
535: }

537: /*@
538:    PEPSetST - Associates a spectral transformation object to the eigensolver.

540:    Collective

542:    Input Parameters:
543: +  pep - eigensolver context obtained from PEPCreate()
544: -  st   - the spectral transformation object

546:    Note:
547:    Use PEPGetST() to retrieve the spectral transformation context (for example,
548:    to free it at the end of the computations).

550:    Level: advanced

552: .seealso: `PEPGetST()`
553: @*/
554: PetscErrorCode PEPSetST(PEP pep,ST st)
555: {
556:   PetscFunctionBegin;
559:   PetscCheckSameComm(pep,1,st,2);
560:   PetscCall(PetscObjectReference((PetscObject)st));
561:   PetscCall(STDestroy(&pep->st));
562:   pep->st = st;
563:   PetscFunctionReturn(PETSC_SUCCESS);
564: }

566: /*@
567:    PEPGetST - Obtain the spectral transformation (ST) object associated
568:    to the eigensolver object.

570:    Not Collective

572:    Input Parameters:
573: .  pep - eigensolver context obtained from PEPCreate()

575:    Output Parameter:
576: .  st - spectral transformation context

578:    Level: intermediate

580: .seealso: `PEPSetST()`
581: @*/
582: PetscErrorCode PEPGetST(PEP pep,ST *st)
583: {
584:   PetscFunctionBegin;
586:   PetscAssertPointer(st,2);
587:   if (!pep->st) {
588:     PetscCall(STCreate(PetscObjectComm((PetscObject)pep),&pep->st));
589:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)pep->st,(PetscObject)pep,0));
590:     PetscCall(PetscObjectSetOptions((PetscObject)pep->st,((PetscObject)pep)->options));
591:   }
592:   *st = pep->st;
593:   PetscFunctionReturn(PETSC_SUCCESS);
594: }

596: /*@
597:    PEPRefineGetKSP - Obtain the ksp object used by the eigensolver
598:    object in the refinement phase.

600:    Collective

602:    Input Parameters:
603: .  pep - eigensolver context obtained from PEPCreate()

605:    Output Parameter:
606: .  ksp - ksp context

608:    Level: advanced

610: .seealso: `PEPSetRefine()`
611: @*/
612: PetscErrorCode PEPRefineGetKSP(PEP pep,KSP *ksp)
613: {
614:   MPI_Comm       comm;

616:   PetscFunctionBegin;
618:   PetscAssertPointer(ksp,2);
619:   if (!pep->refineksp) {
620:     if (pep->npart>1) {
621:       /* Split in subcomunicators */
622:       PetscCall(PetscSubcommCreate(PetscObjectComm((PetscObject)pep),&pep->refinesubc));
623:       PetscCall(PetscSubcommSetNumber(pep->refinesubc,pep->npart));
624:       PetscCall(PetscSubcommSetType(pep->refinesubc,PETSC_SUBCOMM_CONTIGUOUS));
625:       PetscCall(PetscSubcommGetChild(pep->refinesubc,&comm));
626:     } else PetscCall(PetscObjectGetComm((PetscObject)pep,&comm));
627:     PetscCall(KSPCreate(comm,&pep->refineksp));
628:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)pep->refineksp,(PetscObject)pep,0));
629:     PetscCall(PetscObjectSetOptions((PetscObject)pep->refineksp,((PetscObject)pep)->options));
630:     PetscCall(KSPSetOptionsPrefix(*ksp,((PetscObject)pep)->prefix));
631:     PetscCall(KSPAppendOptionsPrefix(*ksp,"pep_refine_"));
632:     PetscCall(KSPSetTolerances(pep->refineksp,SlepcDefaultTol(pep->rtol),PETSC_CURRENT,PETSC_CURRENT,PETSC_CURRENT));
633:   }
634:   *ksp = pep->refineksp;
635:   PetscFunctionReturn(PETSC_SUCCESS);
636: }

638: /*@
639:    PEPSetTarget - Sets the value of the target.

641:    Logically Collective

643:    Input Parameters:
644: +  pep    - eigensolver context
645: -  target - the value of the target

647:    Options Database Key:
648: .  -pep_target <scalar> - the value of the target

650:    Notes:
651:    The target is a scalar value used to determine the portion of the spectrum
652:    of interest. It is used in combination with PEPSetWhichEigenpairs().

654:    In the case of complex scalars, a complex value can be provided in the
655:    command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
656:    -pep_target 1.0+2.0i

658:    Level: intermediate

660: .seealso: `PEPGetTarget()`, `PEPSetWhichEigenpairs()`
661: @*/
662: PetscErrorCode PEPSetTarget(PEP pep,PetscScalar target)
663: {
664:   PetscFunctionBegin;
667:   pep->target = target;
668:   if (!pep->st) PetscCall(PEPGetST(pep,&pep->st));
669:   PetscCall(STSetDefaultShift(pep->st,target));
670:   PetscFunctionReturn(PETSC_SUCCESS);
671: }

673: /*@
674:    PEPGetTarget - Gets the value of the target.

676:    Not Collective

678:    Input Parameter:
679: .  pep - eigensolver context

681:    Output Parameter:
682: .  target - the value of the target

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

687:    Level: intermediate

689: .seealso: `PEPSetTarget()`
690: @*/
691: PetscErrorCode PEPGetTarget(PEP pep,PetscScalar* target)
692: {
693:   PetscFunctionBegin;
695:   PetscAssertPointer(target,2);
696:   *target = pep->target;
697:   PetscFunctionReturn(PETSC_SUCCESS);
698: }

700: /*@
701:    PEPSetInterval - Defines the computational interval for spectrum slicing.

703:    Logically Collective

705:    Input Parameters:
706: +  pep  - eigensolver context
707: .  inta - left end of the interval
708: -  intb - right end of the interval

710:    Options Database Key:
711: .  -pep_interval <a,b> - set [a,b] as the interval of interest

713:    Notes:
714:    Spectrum slicing is a technique employed for computing all eigenvalues of
715:    symmetric eigenproblems in a given interval. This function provides the
716:    interval to be considered. It must be used in combination with PEP_ALL, see
717:    PEPSetWhichEigenpairs().

719:    In the command-line option, two values must be provided. For an open interval,
720:    one can give an infinite, e.g., -pep_interval 1.0,inf or -pep_interval -inf,1.0.
721:    An open interval in the programmatic interface can be specified with
722:    PETSC_MAX_REAL and -PETSC_MAX_REAL.

724:    Level: intermediate

726: .seealso: `PEPGetInterval()`, `PEPSetWhichEigenpairs()`
727: @*/
728: PetscErrorCode PEPSetInterval(PEP pep,PetscReal inta,PetscReal intb)
729: {
730:   PetscFunctionBegin;
734:   PetscCheck(inta<intb,PetscObjectComm((PetscObject)pep),PETSC_ERR_ARG_WRONG,"Badly defined interval, must be inta<intb");
735:   if (pep->inta != inta || pep->intb != intb) {
736:     pep->inta = inta;
737:     pep->intb = intb;
738:     pep->state = PEP_STATE_INITIAL;
739:   }
740:   PetscFunctionReturn(PETSC_SUCCESS);
741: }

743: /*@
744:    PEPGetInterval - Gets the computational interval for spectrum slicing.

746:    Not Collective

748:    Input Parameter:
749: .  pep - eigensolver context

751:    Output Parameters:
752: +  inta - left end of the interval
753: -  intb - right end of the interval

755:    Level: intermediate

757:    Note:
758:    If the interval was not set by the user, then zeros are returned.

760: .seealso: `PEPSetInterval()`
761: @*/
762: PetscErrorCode PEPGetInterval(PEP pep,PetscReal* inta,PetscReal* intb)
763: {
764:   PetscFunctionBegin;
766:   if (inta) *inta = pep->inta;
767:   if (intb) *intb = pep->intb;
768:   PetscFunctionReturn(PETSC_SUCCESS);
769: }