Actual source code: stset.c
slepc-3.10.1 2018-10-23
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2018, 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] = {"same","different","subset"};
    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->shift_matrix,(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:   STSetDefaultKSP(st);
    146:   KSPSetFromOptions(st->ksp);
    147:   return(0);
    148: }

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

    154:    Logically Collective on ST

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

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

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

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

    174:    Level: advanced

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

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

    199:    Not Collective

    201:    Input Parameters:
    202: .  st  - the spectral transformation context

    204:    Output Parameters:
    205: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    206:          SUBSET_NONZERO_PATTERN

    208:    Level: advanced

    210: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
    211: @*/
    212: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    213: {
    217:   *str = st->str;
    218:   return(0);
    219: }

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

    225:    Logically Collective on ST

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

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

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

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

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

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

    255:    Level: intermediate

    257: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
    258: @*/
    259: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    260: {
    264:   if (st->shift_matrix != mode) {
    265:     st->shift_matrix = mode;
    266:     st->state = ST_STATE_INITIAL;
    267:   }
    268:   return(0);
    269: }

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

    275:    Not Collective

    277:    Input Parameter:
    278: .  st - the spectral transformation context

    280:    Output Parameter:
    281: .  mode - the mode flag

    283:    Level: intermediate

    285: .seealso: STSetMatMode(), STMatMode
    286: @*/
    287: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    288: {
    292:   *mode = st->shift_matrix;
    293:   return(0);
    294: }

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

    300:    Logically Collective on ST

    302:    Input Parameters:
    303: +  st  - the spectral transformation context
    304: -  flg - the boolean flag

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

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

    315:    Level: developer

    317: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
    318: @*/
    319: PetscErrorCode STSetTransform(ST st,PetscBool flg)
    320: {
    324:   if (st->transform != flg) {
    325:     st->transform = flg;
    326:     st->state = ST_STATE_INITIAL;
    327:   }
    328:   return(0);
    329: }

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

    335:    Not Collective

    337:    Input Parameter:
    338: .  st - the spectral transformation context

    340:    Output Parameter:
    341: .  flg - the flag

    343:    Level: developer

    345: .seealso: STSetTransform()
    346: @*/
    347: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
    348: {
    352:   *flg = st->transform;
    353:   return(0);
    354: }