Actual source code: stset.c
slepc-3.21.1 2024-04-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

     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;

     51:   PetscFunctionBegin;
     53:   PetscAssertPointer(type,2);

     55:   PetscCall(PetscObjectTypeCompare((PetscObject)st,type,&match));
     56:   if (match) PetscFunctionReturn(PETSC_SUCCESS);
     57:   STCheckNotSeized(st,1);

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

     62:   PetscTryTypeMethod(st,destroy);
     63:   PetscCall(PetscMemzero(st->ops,sizeof(struct _STOps)));

     65:   st->state   = ST_STATE_INITIAL;
     66:   st->opready = PETSC_FALSE;
     67:   PetscCall(PetscObjectChangeTypeName((PetscObject)st,type));
     68:   PetscCall((*r)(st));
     69:   PetscFunctionReturn(PETSC_SUCCESS);
     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: .  type - name of the spectral transformation

     83:    Level: intermediate

     85: .seealso: STSetType()

     87: @*/
     88: PetscErrorCode STGetType(ST st,STType *type)
     89: {
     90:   PetscFunctionBegin;
     92:   PetscAssertPointer(type,2);
     93:   *type = ((PetscObject)st)->type_name;
     94:   PetscFunctionReturn(PETSC_SUCCESS);
     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

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

    107:    Level: beginner

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

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

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

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

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

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

    139:     PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
    140:     PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject));
    141:   PetscOptionsEnd();

    143:   if (st->usesksp) {
    144:     PetscCall(STSetDefaultKSP(st));
    145:     PetscCall(KSPSetFromOptions(st->ksp));
    146:   }
    147:   PetscFunctionReturn(PETSC_SUCCESS);
    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

    156:    Input Parameters:
    157: +  st  - the spectral transformation context
    158: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
    159:          SUBSET_NONZERO_PATTERN, or UNKNOWN_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), 'subset' (pattern is a subset of the
    165:          first one), or 'unknown'.

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

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

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

    179:    Level: advanced

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

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

    205:    Not Collective

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

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

    214:    Level: advanced

    216: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
    217: @*/
    218: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    219: {
    220:   PetscFunctionBegin;
    222:   PetscAssertPointer(str,2);
    223:   *str = st->str;
    224:   PetscFunctionReturn(PETSC_SUCCESS);
    225: }

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

    231:    Logically Collective

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

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

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

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

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

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

    261:    Level: intermediate

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

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

    283:    Not Collective

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

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

    291:    Level: intermediate

    293: .seealso: STSetMatMode(), STMatMode
    294: @*/
    295: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    296: {
    297:   PetscFunctionBegin;
    299:   PetscAssertPointer(mode,2);
    300:   *mode = st->matmode;
    301:   PetscFunctionReturn(PETSC_SUCCESS);
    302: }

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

    308:    Logically Collective

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

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

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

    323:    Level: developer

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

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

    344:    Not Collective

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

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

    352:    Level: developer

    354: .seealso: STSetTransform()
    355: @*/
    356: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
    357: {
    358:   PetscFunctionBegin;
    360:   PetscAssertPointer(flg,2);
    361:   *flg = st->transform;
    362:   PetscFunctionReturn(PETSC_SUCCESS);
    363: }