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 `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: [](ch:pep), `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 `PEPType` for available methods. The default is `PEPTOAR`.

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

152:    Level: intermediate

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

161:   PetscFunctionBegin;
163:   PetscAssertPointer(type,2);

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

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

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

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

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

183:    Not Collective

185:    Input Parameter:
186: .  pep - the polynomial eigensolver context

188:    Output Parameter:
189: .  type - name of `PEP` method

191:    Level: intermediate

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

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

207:    Not Collective

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

213:    Note:
214:    `PEPRegister()` may be called multiple times to add several user-defined solvers.

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

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

227:    Level: advanced

229: .seealso: [](ch:pep), `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
241:    `PEPMonitorSetFromOptions()`.

243:    Not Collective

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

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

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

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

265:    Then, your monitor can be chosen with the procedural interface via
266: .vb
267:    PEPMonitorSetFromOptions(pep,"-pep_monitor_my_monitor","my_monitor",NULL);
268: .ve
269:    or at runtime via the option `-pep_monitor_my_monitor`.

271:    Level: advanced

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

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

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

292:    Collective

294:    Input Parameter:
295: .  pep - the polynomial eigensolver context

297:    Level: advanced

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

324: /*@
325:    PEPDestroy - Destroys the `PEP` context.

327:    Collective

329:    Input Parameter:
330: .  pep - the polynomial eigensolver context

332:    Level: beginner

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

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

363:    Collective

365:    Input Parameters:
366: +  pep - the polynomial eigensolver context
367: -  bv  - the basis vectors object

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

373:    Level: advanced

375: .seealso: [](ch:pep), `PEPGetBV()`
376: @*/
377: PetscErrorCode PEPSetBV(PEP pep,BV bv)
378: {
379:   PetscFunctionBegin;
382:   PetscCheckSameComm(pep,1,bv,2);
383:   PetscCall(PetscObjectReference((PetscObject)bv));
384:   PetscCall(BVDestroy(&pep->V));
385:   pep->V = bv;
386:   PetscFunctionReturn(PETSC_SUCCESS);
387: }

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

393:    Not Collective

395:    Input Parameter:
396: .  pep - the polynomial eigensolver context

398:    Output Parameter:
399: .  bv - basis vectors context

401:    Level: advanced

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

419: /*@
420:    PEPSetRG - Associates a region object to the polynomial eigensolver.

422:    Collective

424:    Input Parameters:
425: +  pep - the polynomial eigensolver context
426: -  rg  - the region object

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

432:    Level: advanced

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

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

454:    Not Collective

456:    Input Parameter:
457: .  pep - the polynomial eigensolver context

459:    Output Parameter:
460: .  rg - region context

462:    Level: advanced

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

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

483:    Collective

485:    Input Parameters:
486: +  pep - the polynomial eigensolver context
487: -  ds  - the direct solver object

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

493:    Level: advanced

495: .seealso: [](ch:pep), `PEPGetDS()`
496: @*/
497: PetscErrorCode PEPSetDS(PEP pep,DS ds)
498: {
499:   PetscFunctionBegin;
502:   PetscCheckSameComm(pep,1,ds,2);
503:   PetscCall(PetscObjectReference((PetscObject)ds));
504:   PetscCall(DSDestroy(&pep->ds));
505:   pep->ds = ds;
506:   PetscFunctionReturn(PETSC_SUCCESS);
507: }

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

513:    Not Collective

515:    Input Parameter:
516: .  pep - the polynomial eigensolver context

518:    Output Parameter:
519: .  ds - direct solver context

521:    Level: advanced

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

539: /*@
540:    PEPSetST - Associates a spectral transformation object to the eigensolver.

542:    Collective

544:    Input Parameters:
545: +  pep - the polynomial eigensolver context
546: -  st  - the spectral transformation object

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

552:    Level: advanced

554: .seealso: [](ch:pep), `PEPGetST()`
555: @*/
556: PetscErrorCode PEPSetST(PEP pep,ST st)
557: {
558:   PetscFunctionBegin;
561:   PetscCheckSameComm(pep,1,st,2);
562:   PetscCall(PetscObjectReference((PetscObject)st));
563:   PetscCall(STDestroy(&pep->st));
564:   pep->st = st;
565:   PetscFunctionReturn(PETSC_SUCCESS);
566: }

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

572:    Not Collective

574:    Input Parameter:
575: .  pep - the polynomial eigensolver context

577:    Output Parameter:
578: .  st - spectral transformation context

580:    Level: intermediate

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

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

602:    Collective

604:    Input Parameter:
605: .  pep - the polynomial eigensolver context

607:    Output Parameter:
608: .  ksp - ksp context

610:    Level: advanced

612: .seealso: [](ch:pep), `PEPSetRefine()`
613: @*/
614: PetscErrorCode PEPRefineGetKSP(PEP pep,KSP *ksp)
615: {
616:   MPI_Comm       comm;

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

640: /*@
641:    PEPSetTarget - Sets the value of the target.

643:    Logically Collective

645:    Input Parameters:
646: +  pep    - the polynomial eigensolver context
647: -  target - the value of the target

649:    Options Database Key:
650: .  -pep_target <scalar> - the value of the target

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

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

660:    Level: intermediate

662: .seealso: [](ch:pep), `PEPGetTarget()`, `PEPSetWhichEigenpairs()`
663: @*/
664: PetscErrorCode PEPSetTarget(PEP pep,PetscScalar target)
665: {
666:   PetscFunctionBegin;
669:   pep->target = target;
670:   if (!pep->st) PetscCall(PEPGetST(pep,&pep->st));
671:   PetscCall(STSetDefaultShift(pep->st,target));
672:   PetscFunctionReturn(PETSC_SUCCESS);
673: }

675: /*@
676:    PEPGetTarget - Gets the value of the target.

678:    Not Collective

680:    Input Parameter:
681: .  pep - the polynomial eigensolver context

683:    Output Parameter:
684: .  target - the value of the target

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

689:    Level: intermediate

691: .seealso: [](ch:pep), `PEPSetTarget()`
692: @*/
693: PetscErrorCode PEPGetTarget(PEP pep,PetscScalar* target)
694: {
695:   PetscFunctionBegin;
697:   PetscAssertPointer(target,2);
698:   *target = pep->target;
699:   PetscFunctionReturn(PETSC_SUCCESS);
700: }

702: /*@
703:    PEPSetInterval - Defines the computational interval for spectrum slicing.

705:    Logically Collective

707:    Input Parameters:
708: +  pep  - the polynomial eigensolver context
709: .  inta - left end of the interval
710: -  intb - right end of the interval

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

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

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

726:    Level: intermediate

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

745: /*@
746:    PEPGetInterval - Gets the computational interval for spectrum slicing.

748:    Not Collective

750:    Input Parameter:
751: .  pep - the polynomial eigensolver context

753:    Output Parameters:
754: +  inta - left end of the interval
755: -  intb - right end of the interval

757:    Level: intermediate

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

762: .seealso: [](ch:pep), `PEPSetInterval()`
763: @*/
764: PetscErrorCode PEPGetInterval(PEP pep,PetscReal* inta,PetscReal* intb)
765: {
766:   PetscFunctionBegin;
768:   if (inta) *inta = pep->inta;
769:   if (intb) *intb = pep->intb;
770:   PetscFunctionReturn(PETSC_SUCCESS);
771: }