Date: 2024-12-02T08:57:25+00:00

Actual source code: nepbasic.c
slepc-3.22.2 2024-12-02
Report Typos and Errors

      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 NEP routines
     12: */

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

     16: /* Logging support */
     17: PetscClassId      NEP_CLASSID = 0;
     18: PetscLogEvent     NEP_SetUp = 0,NEP_Solve = 0,NEP_Refine = 0,NEP_FunctionEval = 0,NEP_JacobianEval = 0,NEP_Resolvent = 0,NEP_CISS_SVD = 0;

     20: /* List of registered NEP routines */
     21: PetscFunctionList NEPList = NULL;
     22: PetscBool         NEPRegisterAllCalled = PETSC_FALSE;

     24: /* List of registered NEP monitors */
     25: PetscFunctionList NEPMonitorList              = NULL;
     26: PetscFunctionList NEPMonitorCreateList        = NULL;
     27: PetscFunctionList NEPMonitorDestroyList       = NULL;
     28: PetscBool         NEPMonitorRegisterAllCalled = PETSC_FALSE;

     30: /*@
     31:    NEPCreate - Creates the default NEP context.

     33:    Collective

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

     38:    Output Parameter:
     39: .  outnep - location to put the NEP context

     41:    Level: beginner

     43: .seealso: NEPSetUp(), NEPSolve(), NEPDestroy(), NEP
     44: @*/
     45: PetscErrorCode NEPCreate(MPI_Comm comm,NEP *outnep)
     46: {
     47:   NEP            nep;

     49:   PetscFunctionBegin;
     50:   PetscAssertPointer(outnep,2);
     51:   PetscCall(NEPInitializePackage());
     52:   PetscCall(SlepcHeaderCreate(nep,NEP_CLASSID,"NEP","Nonlinear Eigenvalue Problem","NEP",comm,NEPDestroy,NEPView));

     54:   nep->max_it          = PETSC_DETERMINE;
     55:   nep->nev             = 1;
     56:   nep->ncv             = PETSC_DETERMINE;
     57:   nep->mpd             = PETSC_DETERMINE;
     58:   nep->nini            = 0;
     59:   nep->target          = 0.0;
     60:   nep->tol             = PETSC_DETERMINE;
     61:   nep->conv            = NEP_CONV_REL;
     62:   nep->stop            = NEP_STOP_BASIC;
     63:   nep->which           = (NEPWhich)0;
     64:   nep->problem_type    = (NEPProblemType)0;
     65:   nep->refine          = NEP_REFINE_NONE;
     66:   nep->npart           = 1;
     67:   nep->rtol            = PETSC_DETERMINE;
     68:   nep->rits            = PETSC_DETERMINE;
     69:   nep->scheme          = (NEPRefineScheme)0;
     70:   nep->trackall        = PETSC_FALSE;
     71:   nep->twosided        = PETSC_FALSE;

     73:   nep->computefunction = NULL;
     74:   nep->computejacobian = NULL;
     75:   nep->functionctx     = NULL;
     76:   nep->jacobianctx     = NULL;
     77:   nep->converged       = NEPConvergedRelative;
     78:   nep->convergeduser   = NULL;
     79:   nep->convergeddestroy= NULL;
     80:   nep->stopping        = NEPStoppingBasic;
     81:   nep->stoppinguser    = NULL;
     82:   nep->stoppingdestroy = NULL;
     83:   nep->convergedctx    = NULL;
     84:   nep->stoppingctx     = NULL;
     85:   nep->numbermonitors  = 0;

     87:   nep->ds              = NULL;
     88:   nep->V               = NULL;
     89:   nep->W               = NULL;
     90:   nep->rg              = NULL;
     91:   nep->function        = NULL;
     92:   nep->function_pre    = NULL;
     93:   nep->jacobian        = NULL;
     94:   nep->A               = NULL;
     95:   nep->f               = NULL;
     96:   nep->nt              = 0;
     97:   nep->mstr            = UNKNOWN_NONZERO_PATTERN;
     98:   nep->P               = NULL;
     99:   nep->mstrp           = UNKNOWN_NONZERO_PATTERN;
    100:   nep->IS              = NULL;
    101:   nep->eigr            = NULL;
    102:   nep->eigi            = NULL;
    103:   nep->errest          = NULL;
    104:   nep->perm            = NULL;
    105:   nep->nwork           = 0;
    106:   nep->work            = NULL;
    107:   nep->data            = NULL;

    109:   nep->state           = NEP_STATE_INITIAL;
    110:   nep->nconv           = 0;
    111:   nep->its             = 0;
    112:   nep->n               = 0;
    113:   nep->nloc            = 0;
    114:   nep->nrma            = NULL;
    115:   nep->fui             = (NEPUserInterface)0;
    116:   nep->useds           = PETSC_FALSE;
    117:   nep->resolvent       = NULL;
    118:   nep->reason          = NEP_CONVERGED_ITERATING;

    120:   PetscCall(PetscNew(&nep->sc));
    121:   *outnep = nep;
    122:   PetscFunctionReturn(PETSC_SUCCESS);
    123: }

    125: /*@
    126:    NEPSetType - Selects the particular solver to be used in the NEP object.

    128:    Logically Collective

    130:    Input Parameters:
    131: +  nep      - the nonlinear eigensolver context
    132: -  type     - a known method

    134:    Options Database Key:
    135: .  -nep_type <method> - Sets the method; use -help for a list
    136:     of available methods

    138:    Notes:
    139:    See "slepc/include/slepcnep.h" for available methods.

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

    149:    Level: intermediate

    151: .seealso: NEPType
    152: @*/
    153: PetscErrorCode NEPSetType(NEP nep,NEPType type)
    154: {
    155:   PetscErrorCode (*r)(NEP);
    156:   PetscBool      match;

    158:   PetscFunctionBegin;
    160:   PetscAssertPointer(type,2);

    162:   PetscCall(PetscObjectTypeCompare((PetscObject)nep,type,&match));
    163:   if (match) PetscFunctionReturn(PETSC_SUCCESS);

    165:   PetscCall(PetscFunctionListFind(NEPList,type,&r));
    166:   PetscCheck(r,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown NEP type given: %s",type);

    168:   PetscTryTypeMethod(nep,destroy);
    169:   PetscCall(PetscMemzero(nep->ops,sizeof(struct _NEPOps)));

    171:   nep->state = NEP_STATE_INITIAL;
    172:   PetscCall(PetscObjectChangeTypeName((PetscObject)nep,type));
    173:   PetscCall((*r)(nep));
    174:   PetscFunctionReturn(PETSC_SUCCESS);
    175: }

    177: /*@
    178:    NEPGetType - Gets the NEP type as a string from the NEP object.

    180:    Not Collective

    182:    Input Parameter:
    183: .  nep - the eigensolver context

    185:    Output Parameter:
    186: .  type - name of NEP method

    188:    Level: intermediate

    190: .seealso: NEPSetType()
    191: @*/
    192: PetscErrorCode NEPGetType(NEP nep,NEPType *type)
    193: {
    194:   PetscFunctionBegin;
    196:   PetscAssertPointer(type,2);
    197:   *type = ((PetscObject)nep)->type_name;
    198:   PetscFunctionReturn(PETSC_SUCCESS);
    199: }

    201: /*@C
    202:    NEPRegister - Adds a method to the nonlinear eigenproblem solver package.

    204:    Not Collective

    206:    Input Parameters:
    207: +  name - name of a new user-defined solver
    208: -  function - routine to create the solver context

    210:    Notes:
    211:    NEPRegister() may be called multiple times to add several user-defined solvers.

    213:    Example Usage:
    214: .vb
    215:     NEPRegister("my_solver",MySolverCreate);
    216: .ve

    218:    Then, your solver can be chosen with the procedural interface via
    219: $     NEPSetType(nep,"my_solver")
    220:    or at runtime via the option
    221: $     -nep_type my_solver

    223:    Level: advanced

    225: .seealso: NEPRegisterAll()
    226: @*/
    227: PetscErrorCode NEPRegister(const char *name,PetscErrorCode (*function)(NEP))
    228: {
    229:   PetscFunctionBegin;
    230:   PetscCall(NEPInitializePackage());
    231:   PetscCall(PetscFunctionListAdd(&NEPList,name,function));
    232:   PetscFunctionReturn(PETSC_SUCCESS);
    233: }

    235: /*@C
    236:    NEPMonitorRegister - Adds NEP monitor routine.

    238:    Not Collective

    240:    Input Parameters:
    241: +  name    - name of a new monitor routine
    242: .  vtype   - a PetscViewerType for the output
    243: .  format  - a PetscViewerFormat for the output
    244: .  monitor - monitor routine
    245: .  create  - creation routine, or NULL
    246: -  destroy - destruction routine, or NULL

    248:    Notes:
    249:    NEPMonitorRegister() may be called multiple times to add several user-defined monitors.

    251:    Example Usage:
    252: .vb
    253:    NEPMonitorRegister("my_monitor",PETSCVIEWERASCII,PETSC_VIEWER_ASCII_INFO_DETAIL,MyMonitor,NULL,NULL);
    254: .ve

    256:    Then, your monitor can be chosen with the procedural interface via
    257: $      NEPMonitorSetFromOptions(nep,"-nep_monitor_my_monitor","my_monitor",NULL)
    258:    or at runtime via the option
    259: $      -nep_monitor_my_monitor

    261:    Level: advanced

    263: .seealso: NEPMonitorRegisterAll()
    264: @*/
    265: PetscErrorCode NEPMonitorRegister(const char name[],PetscViewerType vtype,PetscViewerFormat format,PetscErrorCode (*monitor)(NEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,PetscViewerAndFormat*),PetscErrorCode (*create)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**),PetscErrorCode (*destroy)(PetscViewerAndFormat**))
    266: {
    267:   char           key[PETSC_MAX_PATH_LEN];

    269:   PetscFunctionBegin;
    270:   PetscCall(NEPInitializePackage());
    271:   PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
    272:   PetscCall(PetscFunctionListAdd(&NEPMonitorList,key,monitor));
    273:   if (create)  PetscCall(PetscFunctionListAdd(&NEPMonitorCreateList,key,create));
    274:   if (destroy) PetscCall(PetscFunctionListAdd(&NEPMonitorDestroyList,key,destroy));
    275:   PetscFunctionReturn(PETSC_SUCCESS);
    276: }

    278: /*
    279:    NEPReset_Problem - Destroys the problem matrices.
    280: */
    281: PetscErrorCode NEPReset_Problem(NEP nep)
    282: {
    283:   PetscInt       i;

    285:   PetscFunctionBegin;
    287:   PetscCall(MatDestroy(&nep->function));
    288:   PetscCall(MatDestroy(&nep->function_pre));
    289:   PetscCall(MatDestroy(&nep->jacobian));
    290:   if (nep->fui==NEP_USER_INTERFACE_SPLIT) {
    291:     PetscCall(MatDestroyMatrices(nep->nt,&nep->A));
    292:     for (i=0;i<nep->nt;i++) PetscCall(FNDestroy(&nep->f[i]));
    293:     PetscCall(PetscFree(nep->f));
    294:     PetscCall(PetscFree(nep->nrma));
    295:     if (nep->P) PetscCall(MatDestroyMatrices(nep->nt,&nep->P));
    296:     nep->nt = 0;
    297:   }
    298:   PetscFunctionReturn(PETSC_SUCCESS);
    299: }
    300: /*@
    301:    NEPReset - Resets the NEP context to the initial state (prior to setup)
    302:    and destroys any allocated Vecs and Mats.

    304:    Collective

    306:    Input Parameter:
    307: .  nep - eigensolver context obtained from NEPCreate()

    309:    Level: advanced

    311: .seealso: NEPDestroy()
    312: @*/
    313: PetscErrorCode NEPReset(NEP nep)
    314: {
    315:   PetscFunctionBegin;
    317:   if (!nep) PetscFunctionReturn(PETSC_SUCCESS);
    318:   PetscTryTypeMethod(nep,reset);
    319:   if (nep->refineksp) PetscCall(KSPReset(nep->refineksp));
    320:   PetscCall(NEPReset_Problem(nep));
    321:   PetscCall(BVDestroy(&nep->V));
    322:   PetscCall(BVDestroy(&nep->W));
    323:   PetscCall(VecDestroyVecs(nep->nwork,&nep->work));
    324:   PetscCall(MatDestroy(&nep->resolvent));
    325:   nep->nwork = 0;
    326:   nep->state = NEP_STATE_INITIAL;
    327:   PetscFunctionReturn(PETSC_SUCCESS);
    328: }

    330: /*@
    331:    NEPDestroy - Destroys the NEP context.

    333:    Collective

    335:    Input Parameter:
    336: .  nep - eigensolver context obtained from NEPCreate()

    338:    Level: beginner

    340: .seealso: NEPCreate(), NEPSetUp(), NEPSolve()
    341: @*/
    342: PetscErrorCode NEPDestroy(NEP *nep)
    343: {
    344:   PetscFunctionBegin;
    345:   if (!*nep) PetscFunctionReturn(PETSC_SUCCESS);
    347:   if (--((PetscObject)*nep)->refct > 0) { *nep = NULL; PetscFunctionReturn(PETSC_SUCCESS); }
    348:   PetscCall(NEPReset(*nep));
    349:   PetscTryTypeMethod(*nep,destroy);
    350:   if ((*nep)->eigr) PetscCall(PetscFree4((*nep)->eigr,(*nep)->eigi,(*nep)->errest,(*nep)->perm));
    351:   PetscCall(RGDestroy(&(*nep)->rg));
    352:   PetscCall(DSDestroy(&(*nep)->ds));
    353:   PetscCall(KSPDestroy(&(*nep)->refineksp));
    354:   PetscCall(PetscSubcommDestroy(&(*nep)->refinesubc));
    355:   PetscCall(PetscFree((*nep)->sc));
    356:   /* just in case the initial vectors have not been used */
    357:   PetscCall(SlepcBasisDestroy_Private(&(*nep)->nini,&(*nep)->IS));
    358:   if ((*nep)->convergeddestroy) PetscCall((*(*nep)->convergeddestroy)((*nep)->convergedctx));
    359:   PetscCall(NEPMonitorCancel(*nep));
    360:   PetscCall(PetscHeaderDestroy(nep));
    361:   PetscFunctionReturn(PETSC_SUCCESS);
    362: }

    364: /*@
    365:    NEPSetBV - Associates a basis vectors object to the nonlinear eigensolver.

    367:    Collective

    369:    Input Parameters:
    370: +  nep - eigensolver context obtained from NEPCreate()
    371: -  bv  - the basis vectors object

    373:    Note:
    374:    Use NEPGetBV() to retrieve the basis vectors context (for example,
    375:    to free it at the end of the computations).

    377:    Level: advanced

    379: .seealso: NEPGetBV()
    380: @*/
    381: PetscErrorCode NEPSetBV(NEP nep,BV bv)
    382: {
    383:   PetscFunctionBegin;
    386:   PetscCheckSameComm(nep,1,bv,2);
    387:   PetscCall(PetscObjectReference((PetscObject)bv));
    388:   PetscCall(BVDestroy(&nep->V));
    389:   nep->V = bv;
    390:   PetscFunctionReturn(PETSC_SUCCESS);
    391: }

    393: /*@
    394:    NEPGetBV - Obtain the basis vectors object associated to the nonlinear
    395:    eigensolver object.

    397:    Not Collective

    399:    Input Parameters:
    400: .  nep - eigensolver context obtained from NEPCreate()

    402:    Output Parameter:
    403: .  bv - basis vectors context

    405:    Level: advanced

    407: .seealso: NEPSetBV()
    408: @*/
    409: PetscErrorCode NEPGetBV(NEP nep,BV *bv)
    410: {
    411:   PetscFunctionBegin;
    413:   PetscAssertPointer(bv,2);
    414:   if (!nep->V) {
    415:     PetscCall(BVCreate(PetscObjectComm((PetscObject)nep),&nep->V));
    416:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)nep->V,(PetscObject)nep,0));
    417:     PetscCall(PetscObjectSetOptions((PetscObject)nep->V,((PetscObject)nep)->options));
    418:   }
    419:   *bv = nep->V;
    420:   PetscFunctionReturn(PETSC_SUCCESS);
    421: }

    423: /*@
    424:    NEPSetRG - Associates a region object to the nonlinear eigensolver.

    426:    Collective

    428:    Input Parameters:
    429: +  nep - eigensolver context obtained from NEPCreate()
    430: -  rg  - the region object

    432:    Note:
    433:    Use NEPGetRG() to retrieve the region context (for example,
    434:    to free it at the end of the computations).

    436:    Level: advanced

    438: .seealso: NEPGetRG()
    439: @*/
    440: PetscErrorCode NEPSetRG(NEP nep,RG rg)
    441: {
    442:   PetscFunctionBegin;
    444:   if (rg) {
    446:     PetscCheckSameComm(nep,1,rg,2);
    447:   }
    448:   PetscCall(PetscObjectReference((PetscObject)rg));
    449:   PetscCall(RGDestroy(&nep->rg));
    450:   nep->rg = rg;
    451:   PetscFunctionReturn(PETSC_SUCCESS);
    452: }

    454: /*@
    455:    NEPGetRG - Obtain the region object associated to the
    456:    nonlinear eigensolver object.

    458:    Not Collective

    460:    Input Parameters:
    461: .  nep - eigensolver context obtained from NEPCreate()

    463:    Output Parameter:
    464: .  rg - region context

    466:    Level: advanced

    468: .seealso: NEPSetRG()
    469: @*/
    470: PetscErrorCode NEPGetRG(NEP nep,RG *rg)
    471: {
    472:   PetscFunctionBegin;
    474:   PetscAssertPointer(rg,2);
    475:   if (!nep->rg) {
    476:     PetscCall(RGCreate(PetscObjectComm((PetscObject)nep),&nep->rg));
    477:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)nep->rg,(PetscObject)nep,0));
    478:     PetscCall(PetscObjectSetOptions((PetscObject)nep->rg,((PetscObject)nep)->options));
    479:   }
    480:   *rg = nep->rg;
    481:   PetscFunctionReturn(PETSC_SUCCESS);
    482: }

    484: /*@
    485:    NEPSetDS - Associates a direct solver object to the nonlinear eigensolver.

    487:    Collective

    489:    Input Parameters:
    490: +  nep - eigensolver context obtained from NEPCreate()
    491: -  ds  - the direct solver object

    493:    Note:
    494:    Use NEPGetDS() to retrieve the direct solver context (for example,
    495:    to free it at the end of the computations).

    497:    Level: advanced

    499: .seealso: NEPGetDS()
    500: @*/
    501: PetscErrorCode NEPSetDS(NEP nep,DS ds)
    502: {
    503:   PetscFunctionBegin;
    506:   PetscCheckSameComm(nep,1,ds,2);
    507:   PetscCall(PetscObjectReference((PetscObject)ds));
    508:   PetscCall(DSDestroy(&nep->ds));
    509:   nep->ds = ds;
    510:   PetscFunctionReturn(PETSC_SUCCESS);
    511: }

    513: /*@
    514:    NEPGetDS - Obtain the direct solver object associated to the
    515:    nonlinear eigensolver object.

    517:    Not Collective

    519:    Input Parameters:
    520: .  nep - eigensolver context obtained from NEPCreate()

    522:    Output Parameter:
    523: .  ds - direct solver context

    525:    Level: advanced

    527: .seealso: NEPSetDS()
    528: @*/
    529: PetscErrorCode NEPGetDS(NEP nep,DS *ds)
    530: {
    531:   PetscFunctionBegin;
    533:   PetscAssertPointer(ds,2);
    534:   if (!nep->ds) {
    535:     PetscCall(DSCreate(PetscObjectComm((PetscObject)nep),&nep->ds));
    536:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)nep->ds,(PetscObject)nep,0));
    537:     PetscCall(PetscObjectSetOptions((PetscObject)nep->ds,((PetscObject)nep)->options));
    538:   }
    539:   *ds = nep->ds;
    540:   PetscFunctionReturn(PETSC_SUCCESS);
    541: }

    543: /*@
    544:    NEPRefineGetKSP - Obtain the ksp object used by the eigensolver
    545:    object in the refinement phase.

    547:    Collective

    549:    Input Parameters:
    550: .  nep - eigensolver context obtained from NEPCreate()

    552:    Output Parameter:
    553: .  ksp - ksp context

    555:    Level: advanced

    557: .seealso: NEPSetRefine()
    558: @*/
    559: PetscErrorCode NEPRefineGetKSP(NEP nep,KSP *ksp)
    560: {
    561:   MPI_Comm       comm;

    563:   PetscFunctionBegin;
    565:   PetscAssertPointer(ksp,2);
    566:   if (!nep->refineksp) {
    567:     if (nep->npart>1) {
    568:       /* Split in subcomunicators */
    569:       PetscCall(PetscSubcommCreate(PetscObjectComm((PetscObject)nep),&nep->refinesubc));
    570:       PetscCall(PetscSubcommSetNumber(nep->refinesubc,nep->npart));
    571:       PetscCall(PetscSubcommSetType(nep->refinesubc,PETSC_SUBCOMM_CONTIGUOUS));
    572:       PetscCall(PetscSubcommGetChild(nep->refinesubc,&comm));
    573:     } else PetscCall(PetscObjectGetComm((PetscObject)nep,&comm));
    574:     PetscCall(KSPCreate(comm,&nep->refineksp));
    575:     PetscCall(PetscObjectIncrementTabLevel((PetscObject)nep->refineksp,(PetscObject)nep,0));
    576:     PetscCall(PetscObjectSetOptions((PetscObject)nep->refineksp,((PetscObject)nep)->options));
    577:     PetscCall(KSPSetOptionsPrefix(*ksp,((PetscObject)nep)->prefix));
    578:     PetscCall(KSPAppendOptionsPrefix(*ksp,"nep_refine_"));
    579:     PetscCall(KSPSetTolerances(nep->refineksp,SlepcDefaultTol(nep->rtol),PETSC_CURRENT,PETSC_CURRENT,PETSC_CURRENT));
    580:   }
    581:   *ksp = nep->refineksp;
    582:   PetscFunctionReturn(PETSC_SUCCESS);
    583: }

    585: /*@
    586:    NEPSetTarget - Sets the value of the target.

    588:    Logically Collective

    590:    Input Parameters:
    591: +  nep    - eigensolver context
    592: -  target - the value of the target

    594:    Options Database Key:
    595: .  -nep_target <scalar> - the value of the target

    597:    Notes:
    598:    The target is a scalar value used to determine the portion of the spectrum
    599:    of interest. It is used in combination with NEPSetWhichEigenpairs().

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

    605:    Level: intermediate

    607: .seealso: NEPGetTarget(), NEPSetWhichEigenpairs()
    608: @*/
    609: PetscErrorCode NEPSetTarget(NEP nep,PetscScalar target)
    610: {
    611:   PetscFunctionBegin;
    614:   nep->target = target;
    615:   PetscFunctionReturn(PETSC_SUCCESS);
    616: }

    618: /*@
    619:    NEPGetTarget - Gets the value of the target.

    621:    Not Collective

    623:    Input Parameter:
    624: .  nep - eigensolver context

    626:    Output Parameter:
    627: .  target - the value of the target

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

    632:    Level: intermediate

    634: .seealso: NEPSetTarget()
    635: @*/
    636: PetscErrorCode NEPGetTarget(NEP nep,PetscScalar* target)
    637: {
    638:   PetscFunctionBegin;
    640:   PetscAssertPointer(target,2);
    641:   *target = nep->target;
    642:   PetscFunctionReturn(PETSC_SUCCESS);
    643: }

    645: /*@C
    646:    NEPSetFunction - Sets the function to compute the nonlinear Function T(lambda)
    647:    as well as the location to store the matrix.

    649:    Collective

    651:    Input Parameters:
    652: +  nep - the NEP context
    653: .  A   - Function matrix
    654: .  B   - preconditioner matrix (usually same as A)
    655: .  fun - Function evaluation routine (if NULL then NEP retains any
    656:          previously set value), see NEPFunctionFn for the calling sequence
    657: -  ctx - [optional] user-defined context for private data for the Function
    658:          evaluation routine (may be NULL) (if NULL then NEP retains any
    659:          previously set value)

    661:    Level: beginner

    663: .seealso: NEPGetFunction(), NEPSetJacobian()
    664: @*/
    665: PetscErrorCode NEPSetFunction(NEP nep,Mat A,Mat B,NEPFunctionFn *fun,void *ctx)
    666: {
    667:   PetscFunctionBegin;
    671:   if (A) PetscCheckSameComm(nep,1,A,2);
    672:   if (B) PetscCheckSameComm(nep,1,B,3);

    674:   if (nep->state) PetscCall(NEPReset(nep));
    675:   else if (nep->fui && nep->fui!=NEP_USER_INTERFACE_CALLBACK) PetscCall(NEPReset_Problem(nep));

    677:   if (fun) nep->computefunction = fun;
    678:   if (ctx) nep->functionctx     = ctx;
    679:   if (A) {
    680:     PetscCall(PetscObjectReference((PetscObject)A));
    681:     PetscCall(MatDestroy(&nep->function));
    682:     nep->function = A;
    683:   }
    684:   if (B) {
    685:     PetscCall(PetscObjectReference((PetscObject)B));
    686:     PetscCall(MatDestroy(&nep->function_pre));
    687:     nep->function_pre = B;
    688:   }
    689:   nep->fui   = NEP_USER_INTERFACE_CALLBACK;
    690:   nep->state = NEP_STATE_INITIAL;
    691:   PetscFunctionReturn(PETSC_SUCCESS);
    692: }

    694: /*@C
    695:    NEPGetFunction - Returns the Function matrix and optionally the user
    696:    provided context for evaluating the Function.

    698:    Not Collective

    700:    Input Parameter:
    701: .  nep - the nonlinear eigensolver context

    703:    Output Parameters:
    704: +  A   - location to stash Function matrix (or NULL)
    705: .  B   - location to stash preconditioner matrix (or NULL)
    706: .  fun - location to put Function function (or NULL)
    707: -  ctx - location to stash Function context (or NULL)

    709:    Level: advanced

    711: .seealso: NEPSetFunction()
    712: @*/
    713: PetscErrorCode NEPGetFunction(NEP nep,Mat *A,Mat *B,NEPFunctionFn **fun,void **ctx)
    714: {
    715:   PetscFunctionBegin;
    717:   NEPCheckCallback(nep,1);
    718:   if (A)   *A   = nep->function;
    719:   if (B)   *B   = nep->function_pre;
    720:   if (fun) *fun = nep->computefunction;
    721:   if (ctx) *ctx = nep->functionctx;
    722:   PetscFunctionReturn(PETSC_SUCCESS);
    723: }

    725: /*@C
    726:    NEPSetJacobian - Sets the function to compute the Jacobian T'(lambda) as well
    727:    as the location to store the matrix.

    729:    Collective

    731:    Input Parameters:
    732: +  nep - the NEP context
    733: .  A   - Jacobian matrix
    734: .  jac - Jacobian evaluation routine (if NULL then NEP retains any
    735:          previously set value), see NEPJacobianFn for the calling sequence
    736: -  ctx - [optional] user-defined context for private data for the Jacobian
    737:          evaluation routine (may be NULL) (if NULL then NEP retains any
    738:          previously set value)

    740:    Level: beginner

    742: .seealso: NEPSetFunction(), NEPGetJacobian()
    743: @*/
    744: PetscErrorCode NEPSetJacobian(NEP nep,Mat A,NEPJacobianFn *jac,void *ctx)
    745: {
    746:   PetscFunctionBegin;
    749:   if (A) PetscCheckSameComm(nep,1,A,2);

    751:   if (nep->state) PetscCall(NEPReset(nep));
    752:   else if (nep->fui && nep->fui!=NEP_USER_INTERFACE_CALLBACK) PetscCall(NEPReset_Problem(nep));

    754:   if (jac) nep->computejacobian = jac;
    755:   if (ctx) nep->jacobianctx     = ctx;
    756:   if (A) {
    757:     PetscCall(PetscObjectReference((PetscObject)A));
    758:     PetscCall(MatDestroy(&nep->jacobian));
    759:     nep->jacobian = A;
    760:   }
    761:   nep->fui   = NEP_USER_INTERFACE_CALLBACK;
    762:   nep->state = NEP_STATE_INITIAL;
    763:   PetscFunctionReturn(PETSC_SUCCESS);
    764: }

    766: /*@C
    767:    NEPGetJacobian - Returns the Jacobian matrix and optionally the user
    768:    provided routine and context for evaluating the Jacobian.

    770:    Not Collective

    772:    Input Parameter:
    773: .  nep - the nonlinear eigensolver context

    775:    Output Parameters:
    776: +  A   - location to stash Jacobian matrix (or NULL)
    777: .  jac - location to put Jacobian function (or NULL)
    778: -  ctx - location to stash Jacobian context (or NULL)

    780:    Level: advanced

    782: .seealso: NEPSetJacobian()
    783: @*/
    784: PetscErrorCode NEPGetJacobian(NEP nep,Mat *A,NEPJacobianFn **jac,void **ctx)
    785: {
    786:   PetscFunctionBegin;
    788:   NEPCheckCallback(nep,1);
    789:   if (A)   *A   = nep->jacobian;
    790:   if (jac) *jac = nep->computejacobian;
    791:   if (ctx) *ctx = nep->jacobianctx;
    792:   PetscFunctionReturn(PETSC_SUCCESS);
    793: }

    795: /*@
    796:    NEPSetSplitOperator - Sets the operator of the nonlinear eigenvalue problem
    797:    in split form.

    799:    Collective

    801:    Input Parameters:
    802: +  nep - the nonlinear eigensolver context
    803: .  nt  - number of terms in the split form
    804: .  A   - array of matrices
    805: .  f   - array of functions
    806: -  str - structure flag for matrices

    808:    Notes:
    809:    The nonlinear operator is written as T(lambda) = sum_i A_i*f_i(lambda),
    810:    for i=1,...,n. The derivative T'(lambda) can be obtained using the
    811:    derivatives of f_i.

    813:    The structure flag provides information about A_i's nonzero pattern
    814:    (see MatStructure enum). If all matrices have the same pattern, then
    815:    use SAME_NONZERO_PATTERN. If the patterns are different but contained
    816:    in the pattern of the first one, then use SUBSET_NONZERO_PATTERN. If
    817:    patterns are known to be different, use DIFFERENT_NONZERO_PATTERN.
    818:    If set to UNKNOWN_NONZERO_PATTERN, the patterns will be compared to
    819:    determine if they are equal.

    821:    This function must be called before NEPSetUp(). If it is called again
    822:    after NEPSetUp() then the NEP object is reset.

    824:    Level: beginner

    826: .seealso: NEPGetSplitOperatorTerm(), NEPGetSplitOperatorInfo(), NEPSetSplitPreconditioner()
    827: @*/
    828: PetscErrorCode NEPSetSplitOperator(NEP nep,PetscInt nt,Mat A[],FN f[],MatStructure str)
    829: {
    830:   PetscInt       i,n=0,m,m0=0,mloc,nloc,mloc0=0;

    832:   PetscFunctionBegin;
    835:   PetscCheck(nt>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more terms, you have %" PetscInt_FMT,nt);
    836:   PetscAssertPointer(A,3);
    837:   PetscAssertPointer(f,4);

    840:   for (i=0;i<nt;i++) {
    842:     PetscCheckSameComm(nep,1,A[i],3);
    844:     PetscCheckSameComm(nep,1,f[i],4);
    845:     PetscCall(MatGetSize(A[i],&m,&n));
    846:     PetscCall(MatGetLocalSize(A[i],&mloc,&nloc));
    847:     PetscCheck(m==n,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"A[%" PetscInt_FMT "] is a non-square matrix (%" PetscInt_FMT " rows, %" PetscInt_FMT " cols)",i,m,n);
    848:     PetscCheck(mloc==nloc,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"A[%" PetscInt_FMT "] does not have equal row and column local sizes (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,mloc,nloc);
    849:     if (!i) { m0 = m; mloc0 = mloc; }
    850:     PetscCheck(m==m0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_INCOMP,"Dimensions of A[%" PetscInt_FMT "] do not match with previous matrices (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,m,m0);
    851:     PetscCheck(mloc==mloc0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_INCOMP,"Local dimensions of A[%" PetscInt_FMT "] do not match with previous matrices (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,mloc,mloc0);
    852:     PetscCall(PetscObjectReference((PetscObject)A[i]));
    853:     PetscCall(PetscObjectReference((PetscObject)f[i]));
    854:   }

    856:   if (nep->state && (n!=nep->n || nloc!=nep->nloc)) PetscCall(NEPReset(nep));
    857:   else PetscCall(NEPReset_Problem(nep));

    859:   /* allocate space and copy matrices and functions */
    860:   PetscCall(PetscMalloc1(nt,&nep->A));
    861:   for (i=0;i<nt;i++) nep->A[i] = A[i];
    862:   PetscCall(PetscMalloc1(nt,&nep->f));
    863:   for (i=0;i<nt;i++) nep->f[i] = f[i];
    864:   PetscCall(PetscCalloc1(nt,&nep->nrma));
    865:   nep->nt    = nt;
    866:   nep->mstr  = str;
    867:   nep->fui   = NEP_USER_INTERFACE_SPLIT;
    868:   nep->state = NEP_STATE_INITIAL;
    869:   PetscFunctionReturn(PETSC_SUCCESS);
    870: }

    872: /*@
    873:    NEPGetSplitOperatorTerm - Gets the matrices and functions associated with
    874:    the nonlinear operator in split form.

    876:    Not Collective

    878:    Input Parameters:
    879: +  nep - the nonlinear eigensolver context
    880: -  k   - the index of the requested term (starting in 0)

    882:    Output Parameters:
    883: +  A - the matrix of the requested term
    884: -  f - the function of the requested term

    886:    Level: intermediate

    888: .seealso: NEPSetSplitOperator(), NEPGetSplitOperatorInfo()
    889: @*/
    890: PetscErrorCode NEPGetSplitOperatorTerm(NEP nep,PetscInt k,Mat *A,FN *f)
    891: {
    892:   PetscFunctionBegin;
    895:   NEPCheckSplit(nep,1);
    896:   PetscCheck(k>=0 && k<nep->nt,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"k must be between 0 and %" PetscInt_FMT,nep->nt-1);
    897:   if (A) *A = nep->A[k];
    898:   if (f) *f = nep->f[k];
    899:   PetscFunctionReturn(PETSC_SUCCESS);
    900: }

    902: /*@
    903:    NEPGetSplitOperatorInfo - Returns the number of terms of the split form of
    904:    the nonlinear operator, as well as the structure flag for matrices.

    906:    Not Collective

    908:    Input Parameter:
    909: .  nep - the nonlinear eigensolver context

    911:    Output Parameters:
    912: +  n   - the number of terms passed in NEPSetSplitOperator()
    913: -  str - the matrix structure flag passed in NEPSetSplitOperator()

    915:    Level: intermediate

    917: .seealso: NEPSetSplitOperator(), NEPGetSplitOperatorTerm()
    918: @*/
    919: PetscErrorCode NEPGetSplitOperatorInfo(NEP nep,PetscInt *n,MatStructure *str)
    920: {
    921:   PetscFunctionBegin;
    923:   NEPCheckSplit(nep,1);
    924:   if (n)   *n = nep->nt;
    925:   if (str) *str = nep->mstr;
    926:   PetscFunctionReturn(PETSC_SUCCESS);
    927: }

    929: /*@
    930:    NEPSetSplitPreconditioner - Sets an operator in split form from which
    931:    to build the preconditioner to be used when solving the nonlinear
    932:    eigenvalue problem in split form.

    934:    Collective

    936:    Input Parameters:
    937: +  nep  - the nonlinear eigensolver context
    938: .  ntp  - number of terms in the split preconditioner
    939: .  P    - array of matrices
    940: -  strp - structure flag for matrices

    942:    Notes:
    943:    The matrix for the preconditioner is expressed as P(lambda) =
    944:    sum_i P_i*f_i(lambda), for i=1,...,n, where the f_i functions
    945:    are the same as in NEPSetSplitOperator(). It is not necessary to call
    946:    this function. If it is not invoked, then the preconditioner is
    947:    built from T(lambda), i.e., both matrices and functions passed in
    948:    NEPSetSplitOperator().

    950:    The structure flag provides information about P_i's nonzero pattern
    951:    in the same way as in NEPSetSplitOperator().

    953:    If the functions defining the preconditioner operator were different
    954:    from the ones given in NEPSetSplitOperator(), then the split form
    955:    cannot be used. Use the callback interface instead.

    957:    Use ntp=0 to reset a previously set split preconditioner.

    959:    Level: advanced

    961: .seealso: NEPGetSplitPreconditionerTerm(), NEPGetSplitPreconditionerInfo(), NEPSetSplitOperator()
    962: @*/
    963: PetscErrorCode NEPSetSplitPreconditioner(NEP nep,PetscInt ntp,Mat P[],MatStructure strp)
    964: {
    965:   PetscInt       i,n=0,m,m0=0,mloc,nloc,mloc0=0;

    967:   PetscFunctionBegin;
    970:   PetscCheck(ntp>=0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Negative value of ntp = %" PetscInt_FMT,ntp);
    971:   PetscCheck(nep->fui==NEP_USER_INTERFACE_SPLIT,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetSplitOperator first");
    972:   PetscCheck(ntp==0 || nep->nt==ntp,PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"The number of terms must be the same as in NEPSetSplitOperator()");
    973:   if (ntp) PetscAssertPointer(P,3);

    976:   for (i=0;i<ntp;i++) {
    978:     PetscCheckSameComm(nep,1,P[i],3);
    979:     PetscCall(MatGetSize(P[i],&m,&n));
    980:     PetscCall(MatGetLocalSize(P[i],&mloc,&nloc));
    981:     PetscCheck(m==n,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"P[%" PetscInt_FMT "] is a non-square matrix (%" PetscInt_FMT " rows, %" PetscInt_FMT " cols)",i,m,n);
    982:     PetscCheck(mloc==nloc,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"P[%" PetscInt_FMT "] does not have equal row and column local sizes (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,mloc,nloc);
    983:     if (!i) { m0 = m; mloc0 = mloc; }
    984:     PetscCheck(m==m0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_INCOMP,"Dimensions of P[%" PetscInt_FMT "] do not match with previous matrices (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,m,m0);
    985:     PetscCheck(mloc==mloc0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_INCOMP,"Local dimensions of P[%" PetscInt_FMT "] do not match with previous matrices (%" PetscInt_FMT ", %" PetscInt_FMT ")",i,mloc,mloc0);
    986:     PetscCall(PetscObjectReference((PetscObject)P[i]));
    987:   }

    989:   PetscCheck(!nep->state,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"To call this function after NEPSetUp(), you must call NEPSetSplitOperator() again");
    990:   if (nep->P) PetscCall(MatDestroyMatrices(nep->nt,&nep->P));

    992:   /* allocate space and copy matrices */
    993:   if (ntp) {
    994:     PetscCall(PetscMalloc1(ntp,&nep->P));
    995:     for (i=0;i<ntp;i++) nep->P[i] = P[i];
    996:   }
    997:   nep->mstrp = strp;
    998:   nep->state = NEP_STATE_INITIAL;
    999:   PetscFunctionReturn(PETSC_SUCCESS);
    1000: }

    1002: /*@
    1003:    NEPGetSplitPreconditionerTerm - Gets the matrices associated with
    1004:    the split preconditioner.

    1006:    Not Collective

    1008:    Input Parameters:
    1009: +  nep - the nonlinear eigensolver context
    1010: -  k   - the index of the requested term (starting in 0)

    1012:    Output Parameter:
    1013: .  P  - the matrix of the requested term

    1015:    Level: advanced

    1017: .seealso: NEPSetSplitPreconditioner(), NEPGetSplitPreconditionerInfo()
    1018: @*/
    1019: PetscErrorCode NEPGetSplitPreconditionerTerm(NEP nep,PetscInt k,Mat *P)
    1020: {
    1021:   PetscFunctionBegin;
    1024:   PetscAssertPointer(P,3);
    1025:   NEPCheckSplit(nep,1);
    1026:   PetscCheck(k>=0 && k<nep->nt,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"k must be between 0 and %" PetscInt_FMT,nep->nt-1);
    1027:   PetscCheck(nep->P,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"You have not called NEPSetSplitPreconditioner()");
    1028:   *P = nep->P[k];
    1029:   PetscFunctionReturn(PETSC_SUCCESS);
    1030: }

    1032: /*@
    1033:    NEPGetSplitPreconditionerInfo - Returns the number of terms of the split
    1034:    preconditioner, as well as the structure flag for matrices.

    1036:    Not Collective

    1038:    Input Parameter:
    1039: .  nep - the nonlinear eigensolver context

    1041:    Output Parameters:
    1042: +  n    - the number of terms passed in NEPSetSplitPreconditioner()
    1043: -  strp - the matrix structure flag passed in NEPSetSplitPreconditioner()

    1045:    Level: advanced

    1047: .seealso: NEPSetSplitPreconditioner(), NEPGetSplitPreconditionerTerm()
    1048: @*/
    1049: PetscErrorCode NEPGetSplitPreconditionerInfo(NEP nep,PetscInt *n,MatStructure *strp)
    1050: {
    1051:   PetscFunctionBegin;
    1053:   NEPCheckSplit(nep,1);
    1054:   if (n)    *n    = nep->P? nep->nt: 0;
    1055:   if (strp) *strp = nep->mstrp;
    1056:   PetscFunctionReturn(PETSC_SUCCESS);
    1057: }