Date: 2022-08-09T09:05:28+00:00

Actual source code: stset.c
slepc-3.17.2 2022-08-09
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:    Routines to set ST methods and options
     12: */

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

     16: PetscBool         STRegisterAllCalled = PETSC_FALSE;
     17: PetscFunctionList STList = 0;

     19: /*@C
     20:    STSetType - Builds ST for a particular spectral transformation.

     22:    Logically Collective on st

     24:    Input Parameters:
     25: +  st   - the spectral transformation context.
     26: -  type - a known type

     28:    Options Database Key:
     29: .  -st_type <type> - Sets ST type

     31:    Use -help for a list of available transformations

     33:    Notes:
     34:    See "slepc/include/slepcst.h" for available transformations

     36:    Normally, it is best to use the EPSSetFromOptions() command and
     37:    then set the ST type from the options database rather than by using
     38:    this routine.  Using the options database provides the user with
     39:    maximum flexibility in evaluating the many different transformations.

     41:    Level: beginner

     43: .seealso: EPSSetType()

     45: @*/
     46: PetscErrorCode STSetType(ST st,STType type)
     47: {
     48:   PetscErrorCode (*r)(ST);
     49:   PetscBool      match;

     54:   PetscObjectTypeCompare((PetscObject)st,type,&match);
     55:   if (match) PetscFunctionReturn(0);
     56:   STCheckNotSeized(st,1);

     58:   PetscFunctionListFind(STList,type,&r);

     61:   if (st->ops->destroy) (*st->ops->destroy)(st);
     62:   PetscMemzero(st->ops,sizeof(struct _STOps));

     64:   st->state   = ST_STATE_INITIAL;
     65:   st->opready = PETSC_FALSE;
     66:   PetscObjectChangeTypeName((PetscObject)st,type);
     67:   (*r)(st);
     68:   PetscFunctionReturn(0);
     69: }

     71: /*@C
     72:    STGetType - Gets the ST type name (as a string) from the ST context.

     74:    Not Collective

     76:    Input Parameter:
     77: .  st - the spectral transformation context

     79:    Output Parameter:
     80: .  type - name of the spectral transformation

     82:    Level: intermediate

     84: .seealso: STSetType()

     86: @*/
     87: PetscErrorCode STGetType(ST st,STType *type)
     88: {
     91:   *type = ((PetscObject)st)->type_name;
     92:   PetscFunctionReturn(0);
     93: }

     95: /*@
     96:    STSetFromOptions - Sets ST options from the options database.
     97:    This routine must be called before STSetUp() if the user is to be
     98:    allowed to set the type of transformation.

    100:    Collective on st

    102:    Input Parameter:
    103: .  st - the spectral transformation context

    105:    Level: beginner

    107: .seealso: STSetOptionsPrefix()
    108: @*/
    109: PetscErrorCode STSetFromOptions(ST st)
    110: {
    112:   PetscScalar    s;
    113:   char           type[256];
    114:   PetscBool      flg,bval;
    115:   STMatMode      mode;
    116:   MatStructure   mstr;

    119:   STRegisterAll();
    120:   ierr = PetscObjectOptionsBegin((PetscObject)st);
    121:     PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg);
    122:     if (flg) STSetType(st,type);
    123:     else if (!((PetscObject)st)->type_name) STSetType(st,STSHIFT);

    125:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
    126:     if (flg) STSetShift(st,s);

    128:     PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg);
    129:     if (flg) STSetMatMode(st,mode);

    131:     PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg);
    132:     if (flg) STSetMatStructure(st,mstr);

    134:     PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg);
    135:     if (flg) STSetTransform(st,bval);

    137:     if (st->ops->setfromoptions) (*st->ops->setfromoptions)(PetscOptionsObject,st);
    138:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
    139:   ierr = PetscOptionsEnd();

    141:   if (st->usesksp) {
    142:     STSetDefaultKSP(st);
    143:     KSPSetFromOptions(st->ksp);
    144:   }
    145:   PetscFunctionReturn(0);
    146: }

    148: /*@
    149:    STSetMatStructure - Sets an internal MatStructure attribute to
    150:    indicate which is the relation of the sparsity pattern of all ST matrices.

    152:    Logically Collective on st

    154:    Input Parameters:
    155: +  st  - the spectral transformation context
    156: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
    157:          SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN

    159:    Options Database Key:
    160: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
    161:          of 'same' (matrices have the same nonzero pattern), 'different'
    162:          (different nonzero pattern), 'subset' (pattern is a subset of the
    163:          first one), or 'unknown'.

    165:    Notes:
    166:    If the sparsity pattern of the second matrix is equal or a subset of the
    167:    pattern of the first matrix then it is recommended to set this attribute
    168:    for efficiency reasons (in particular, for internal MatAXPY() operations).
    169:    If not set, the default is UNKNOWN_NONZERO_PATTERN, in which case the patterns
    170:    will be compared to determine if they are equal.

    172:    This function has no effect in the case of standard eigenproblems.

    174:    In case of polynomial eigenproblems, the flag applies to all matrices
    175:    relative to the first one.

    177:    Level: advanced

    179: .seealso: STSetMatrices(), MatAXPY()
    180: @*/
    181: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
    182: {
    185:   switch (str) {
    186:     case SAME_NONZERO_PATTERN:
    187:     case DIFFERENT_NONZERO_PATTERN:
    188:     case SUBSET_NONZERO_PATTERN:
    189:     case UNKNOWN_NONZERO_PATTERN:
    190:       st->str = str;
    191:       break;
    192:     default:
    193:       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
    194:   }
    195:   PetscFunctionReturn(0);
    196: }

    198: /*@
    199:    STGetMatStructure - Gets the internal MatStructure attribute to
    200:    indicate which is the relation of the sparsity pattern of the matrices.

    202:    Not Collective

    204:    Input Parameters:
    205: .  st  - the spectral transformation context

    207:    Output Parameters:
    208: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
    209:          SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN

    211:    Level: advanced

    213: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
    214: @*/
    215: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    216: {
    219:   *str = st->str;
    220:   PetscFunctionReturn(0);
    221: }

    223: /*@
    224:    STSetMatMode - Sets a flag to indicate how the transformed matrices are
    225:    being stored in the spectral transformations.

    227:    Logically Collective on st

    229:    Input Parameters:
    230: +  st - the spectral transformation context
    231: -  mode - the mode flag, one of ST_MATMODE_COPY,
    232:           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL

    234:    Options Database Key:
    235: .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
    236:           'copy', 'inplace', 'shell' (see explanation below).

    238:    Notes:
    239:    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
    240:    this copy is modified explicitly, e.g. A <- (A - s B).

    242:    With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
    243:    and changes are reverted at the end of the computations. With respect to
    244:    the previous one, this mode avoids a copy of matrix A. However, a
    245:    drawback is that the recovered matrix might be slightly different
    246:    from the original one (due to roundoff).

    248:    With ST_MATMODE_SHELL, the solver works with an implicit shell
    249:    matrix that represents the shifted matrix. This mode is the most efficient
    250:    in creating the shifted matrix but it places serious limitations to the
    251:    linear solves performed in each iteration of the eigensolver (typically,
    252:    only iterative solvers with Jacobi preconditioning can be used).

    254:    In the two first modes the efficiency of the computation
    255:    can be controlled with STSetMatStructure().

    257:    Level: intermediate

    259: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
    260: @*/
    261: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    262: {
    265:   if (st->matmode != mode) {
    266:     STCheckNotSeized(st,1);
    267:     st->matmode = mode;
    268:     st->state   = ST_STATE_INITIAL;
    269:     st->opready = PETSC_FALSE;
    270:   }
    271:   PetscFunctionReturn(0);
    272: }

    274: /*@
    275:    STGetMatMode - Gets a flag that indicates how the transformed matrices
    276:    are stored in spectral transformations.

    278:    Not Collective

    280:    Input Parameter:
    281: .  st - the spectral transformation context

    283:    Output Parameter:
    284: .  mode - the mode flag

    286:    Level: intermediate

    288: .seealso: STSetMatMode(), STMatMode
    289: @*/
    290: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    291: {
    294:   *mode = st->matmode;
    295:   PetscFunctionReturn(0);
    296: }

    298: /*@
    299:    STSetTransform - Sets a flag to indicate whether the transformed matrices are
    300:    computed or not.

    302:    Logically Collective on st

    304:    Input Parameters:
    305: +  st  - the spectral transformation context
    306: -  flg - the boolean flag

    308:    Options Database Key:
    309: .  -st_transform <bool> - Activate/deactivate the computation of matrices.

    311:    Notes:
    312:    This flag is intended for the case of polynomial eigenproblems solved
    313:    via linearization. If this flag is off (default) the spectral transformation
    314:    is applied to the linearization (handled by the eigensolver), otherwise
    315:    it is applied to the original problem.

    317:    Level: developer

    319: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
    320: @*/
    321: PetscErrorCode STSetTransform(ST st,PetscBool flg)
    322: {
    325:   if (st->transform != flg) {
    326:     st->transform = flg;
    327:     st->state     = ST_STATE_INITIAL;
    328:     st->opready   = PETSC_FALSE;
    329:   }
    330:   PetscFunctionReturn(0);
    331: }

    333: /*@
    334:    STGetTransform - Gets a flag that that indicates whether the transformed
    335:    matrices are computed or not.

    337:    Not Collective

    339:    Input Parameter:
    340: .  st - the spectral transformation context

    342:    Output Parameter:
    343: .  flg - the flag

    345:    Level: developer

    347: .seealso: STSetTransform()
    348: @*/
    349: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
    350: {
    353:   *flg = st->transform;
    354:   PetscFunctionReturn(0);
    355: }