Date: 2020-01-13T11:59:46+00:00

Actual source code: stset.c
slepc-3.12.2 2020-01-13
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2019, 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>      /*I "slepcst.h" I*/

     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 Parameter:
     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 ierr,(*r)(ST);
     49:   PetscBool      match;

     55:   PetscObjectTypeCompare((PetscObject)st,type,&match);
     56:   if (match) return(0);

     58:    PetscFunctionListFind(STList,type,&r);
     59:   if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);

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

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

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

     73:    Not Collective

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

     78:    Output Parameter:
     79: .  name - name of the spectral transformation

     81:    Level: intermediate

     83: .seealso: STSetType()

     85: @*/
     86: PetscErrorCode STGetType(ST st,STType *type)
     87: {
     91:   *type = ((PetscObject)st)->type_name;
     92:   return(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
    106: @*/
    107: PetscErrorCode STSetFromOptions(ST st)
    108: {
    110:   PetscScalar    s;
    111:   char           type[256];
    112:   PetscBool      flg;
    113:   const char     *structure_list[3] = {"different","subset","same"};
    114:   STMatMode      mode;
    115:   MatStructure   mstr;

    119:   STRegisterAll();
    120:   PetscObjectOptionsBegin((PetscObject)st);
    121:     PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
    122:     if (flg) {
    123:       STSetType(st,type);
    124:     } else if (!((PetscObject)st)->type_name) {
    125:       STSetType(st,STSHIFT);
    126:     }

    128:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
    129:     if (flg) { STSetShift(st,s); }

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

    134:     PetscOptionsEList("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",structure_list,3,structure_list[st->str],(PetscInt*)&mstr,&flg);
    135:     if (flg) { STSetMatStructure(st,mstr); }

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

    139:     if (st->ops->setfromoptions) {
    140:       (*st->ops->setfromoptions)(PetscOptionsObject,st);
    141:     }
    142:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
    143:   PetscOptionsEnd();

    145:   if (st->usesksp) {
    146:     STSetDefaultKSP(st);
    147:     KSPSetFromOptions(st->ksp);
    148:   }
    149:   return(0);
    150: }

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

    156:    Logically Collective on st

    158:    Input Parameters:
    159: +  st  - the spectral transformation context
    160: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    161:          SUBSET_NONZERO_PATTERN

    163:    Options Database Key:
    164: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
    165:          of 'same' (matrices have the same nonzero pattern), 'different'
    166:          (different nonzero pattern) or 'subset' (pattern is a subset of the
    167:          first one).

    169:    Notes:
    170:    By default, the sparsity patterns are assumed to be different. If the
    171:    patterns are equal or a subset then it is recommended to set this attribute
    172:    for efficiency reasons (in particular, for internal MatAXPY() operations).

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

    176:    Level: advanced

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

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

    201:    Not Collective

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

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

    210:    Level: advanced

    212: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
    213: @*/
    214: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    215: {
    219:   *str = st->str;
    220:   return(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 interative 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: {
    266:   if (st->matmode != mode) {
    267:     st->matmode = mode;
    268:     st->state = ST_STATE_INITIAL;
    269:   }
    270:   return(0);
    271: }

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

    277:    Not Collective

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

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

    285:    Level: intermediate

    287: .seealso: STSetMatMode(), STMatMode
    288: @*/
    289: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    290: {
    294:   *mode = st->matmode;
    295:   return(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: {
    326:   if (st->transform != flg) {
    327:     st->transform = flg;
    328:     st->state = ST_STATE_INITIAL;
    329:   }
    330:   return(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: {
    354:   *flg = st->transform;
    355:   return(0);
    356: }