Date: 2021-02-01T14:41:50+00:00

Actual source code: stset.c
slepc-3.14.2 2021-02-01
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2020, 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 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);
     57:   STCheckNotSeized(st,1);

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

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

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

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

     75:    Not Collective

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

     80:    Output Parameter:
     81: .  name - name of the spectral transformation

     83:    Level: intermediate

     85: .seealso: STSetType()

     87: @*/
     88: PetscErrorCode STGetType(ST st,STType *type)
     89: {
     93:   *type = ((PetscObject)st)->type_name;
     94:   return(0);
     95: }

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

    102:    Collective on st

    104:    Input Parameter:
    105: .  st - the spectral transformation context

    107:    Level: beginner
    108: @*/
    109: PetscErrorCode STSetFromOptions(ST st)
    110: {
    112:   PetscScalar    s;
    113:   char           type[256];
    114:   PetscBool      flg,bval;
    115:   const char     *structure_list[3] = {"different","subset","same"};
    116:   STMatMode      mode;
    117:   MatStructure   mstr;

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

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

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

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

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

    142:     if (st->ops->setfromoptions) {
    143:       (*st->ops->setfromoptions)(PetscOptionsObject,st);
    144:     }
    145:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
    146:   PetscOptionsEnd();

    148:   if (st->usesksp) {
    149:     STSetDefaultKSP(st);
    150:     KSPSetFromOptions(st->ksp);
    151:   }
    152:   return(0);
    153: }

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

    159:    Logically Collective on st

    161:    Input Parameters:
    162: +  st  - the spectral transformation context
    163: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    164:          SUBSET_NONZERO_PATTERN

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

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

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

    179:    Level: advanced

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

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

    204:    Not Collective

    206:    Input Parameters:
    207: .  st  - the spectral transformation context

    209:    Output Parameters:
    210: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    211:          SUBSET_NONZERO_PATTERN

    213:    Level: advanced

    215: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
    216: @*/
    217: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    218: {
    222:   *str = st->str;
    223:   return(0);
    224: }

    226: /*@
    227:    STSetMatMode - Sets a flag to indicate how the transformed matrices are
    228:    being stored in the spectral transformations.

    230:    Logically Collective on st

    232:    Input Parameters:
    233: +  st - the spectral transformation context
    234: -  mode - the mode flag, one of ST_MATMODE_COPY,
    235:           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL

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

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

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

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

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

    260:    Level: intermediate

    262: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
    263: @*/
    264: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    265: {
    269:   if (st->matmode != mode) {
    270:     STCheckNotSeized(st,1);
    271:     st->matmode = mode;
    272:     st->state   = ST_STATE_INITIAL;
    273:     st->opready = PETSC_FALSE;
    274:   }
    275:   return(0);
    276: }

    278: /*@
    279:    STGetMatMode - Gets a flag that indicates how the transformed matrices
    280:    are stored in spectral transformations.

    282:    Not Collective

    284:    Input Parameter:
    285: .  st - the spectral transformation context

    287:    Output Parameter:
    288: .  mode - the mode flag

    290:    Level: intermediate

    292: .seealso: STSetMatMode(), STMatMode
    293: @*/
    294: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    295: {
    299:   *mode = st->matmode;
    300:   return(0);
    301: }

    303: /*@
    304:    STSetTransform - Sets a flag to indicate whether the transformed matrices are
    305:    computed or not.

    307:    Logically Collective on st

    309:    Input Parameters:
    310: +  st  - the spectral transformation context
    311: -  flg - the boolean flag

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

    316:    Notes:
    317:    This flag is intended for the case of polynomial eigenproblems solved
    318:    via linearization. If this flag is off (default) the spectral transformation
    319:    is applied to the linearization (handled by the eigensolver), otherwise
    320:    it is applied to the original problem.

    322:    Level: developer

    324: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
    325: @*/
    326: PetscErrorCode STSetTransform(ST st,PetscBool flg)
    327: {
    331:   if (st->transform != flg) {
    332:     st->transform = flg;
    333:     st->state     = ST_STATE_INITIAL;
    334:     st->opready   = PETSC_FALSE;
    335:   }
    336:   return(0);
    337: }

    339: /*@
    340:    STGetTransform - Gets a flag that that indicates whether the transformed
    341:    matrices are computed or not.

    343:    Not Collective

    345:    Input Parameter:
    346: .  st - the spectral transformation context

    348:    Output Parameter:
    349: .  flg - the flag

    351:    Level: developer

    353: .seealso: STSetTransform()
    354: @*/
    355: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
    356: {
    360:   *flg = st->transform;
    361:   return(0);
    362: }