Date: 2023-01-26T12:18:20+00:00

Actual source code: stset.c
slepc-3.18.2 2023-01-26
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 = NULL;

     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) return 0;
     56:   STCheckNotSeized(st,1);

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

     61:   PetscTryTypeMethod(st,destroy);
     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:   return 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:   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

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

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

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

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

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

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

    136:     PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
    137:     PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject);
    138:   PetscOptionsEnd();

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

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

    151:    Logically Collective on st

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

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

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

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

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

    176:    Level: advanced

    178: .seealso: STSetMatrices(), MatAXPY()
    179: @*/
    180: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
    181: {
    184:   switch (str) {
    185:     case SAME_NONZERO_PATTERN:
    186:     case DIFFERENT_NONZERO_PATTERN:
    187:     case SUBSET_NONZERO_PATTERN:
    188:     case UNKNOWN_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,
    208:          SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN

    210:    Level: advanced

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

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

    226:    Logically Collective on st

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

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

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

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

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

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

    256:    Level: intermediate

    258: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
    259: @*/
    260: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    261: {
    264:   if (st->matmode != mode) {
    265:     STCheckNotSeized(st,1);
    266:     st->matmode = mode;
    267:     st->state   = ST_STATE_INITIAL;
    268:     st->opready = PETSC_FALSE;
    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: {
    293:   *mode = st->matmode;
    294:   return 0;
    295: }

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

    301:    Logically Collective on st

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

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

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

    316:    Level: developer

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

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

    336:    Not Collective

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

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

    344:    Level: developer

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