Date: 2015-09-03T15:03:53+00:00

Actual source code: stset.c
slepc-3.6.1 2015-09-03
Report Typos and Errors

      1: /*
      2:     Routines to set ST methods and options.

      4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      6:    Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain

      8:    This file is part of SLEPc.

     10:    SLEPc is free software: you can redistribute it and/or modify it under  the
     11:    terms of version 3 of the GNU Lesser General Public License as published by
     12:    the Free Software Foundation.

     14:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
     15:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
     16:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
     17:    more details.

     19:    You  should have received a copy of the GNU Lesser General  Public  License
     20:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
     21:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     22: */

     24: #include <slepc/private/stimpl.h>      /*I "slepcst.h" I*/

     26: PetscBool         STRegisterAllCalled = PETSC_FALSE;
     27: PetscFunctionList STList = 0;

     31: /*@C
     32:    STSetType - Builds ST for a particular spectral transformation.

     34:    Logically Collective on ST

     36:    Input Parameter:
     37: +  st   - the spectral transformation context.
     38: -  type - a known type

     40:    Options Database Key:
     41: .  -st_type <type> - Sets ST type

     43:    Use -help for a list of available transformations

     45:    Notes:
     46:    See "slepc/include/slepcst.h" for available transformations

     48:    Normally, it is best to use the EPSSetFromOptions() command and
     49:    then set the ST type from the options database rather than by using
     50:    this routine.  Using the options database provides the user with
     51:    maximum flexibility in evaluating the many different transformations.

     53:    Level: beginner

     55: .seealso: EPSSetType()

     57: @*/
     58: PetscErrorCode STSetType(ST st,STType type)
     59: {
     60:   PetscErrorCode ierr,(*r)(ST);
     61:   PetscBool      match;

     67:   PetscObjectTypeCompare((PetscObject)st,type,&match);
     68:   if (match) return(0);

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

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

     76:   st->setupcalled = 0;
     77:   PetscObjectChangeTypeName((PetscObject)st,type);
     78:   (*r)(st);
     79:   return(0);
     80: }

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

     87:    Not Collective

     89:    Input Parameter:
     90: .  st - the spectral transformation context

     92:    Output Parameter:
     93: .  name - name of the spectral transformation

     95:    Level: intermediate

     97: .seealso: STSetType()

     99: @*/
    100: PetscErrorCode STGetType(ST st,STType *type)
    101: {
    105:   *type = ((PetscObject)st)->type_name;
    106:   return(0);
    107: }

    111: /*@
    112:    STSetFromOptions - Sets ST options from the options database.
    113:    This routine must be called before STSetUp() if the user is to be
    114:    allowed to set the type of transformation.

    116:    Collective on ST

    118:    Input Parameter:
    119: .  st - the spectral transformation context

    121:    Level: beginner
    122: @*/
    123: PetscErrorCode STSetFromOptions(ST st)
    124: {
    126:   PetscInt       i;
    127:   PetscScalar    s;
    128:   char           type[256];
    129:   PetscBool      flg;
    130:   const char     *mode_list[3] = {"copy","inplace","shell"};
    131:   const char     *structure_list[3] = {"same","different","subset"};

    135:   STRegisterAll();
    136:   PetscObjectOptionsBegin((PetscObject)st);
    137:     PetscOptionsFList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
    138:     if (flg) {
    139:       STSetType(st,type);
    140:     }
    141:     /*
    142:       Set the type if it was never set.
    143:     */
    144:     if (!((PetscObject)st)->type_name) {
    145:       STSetType(st,STSHIFT);
    146:     }

    148:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
    149:     if (flg) {
    150:       STSetShift(st,s);
    151:     }

    153:     PetscOptionsEList("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
    154:     if (flg) st->shift_matrix = (STMatMode)i;

    156:     PetscOptionsEList("-st_matstructure","Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
    157:     if (flg) {
    158:       switch (i) {
    159:         case 0: STSetMatStructure(st,SAME_NONZERO_PATTERN); break;
    160:         case 1: STSetMatStructure(st,DIFFERENT_NONZERO_PATTERN); break;
    161:         case 2: STSetMatStructure(st,SUBSET_NONZERO_PATTERN); break;
    162:       }
    163:     }

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

    167:     if (st->ops->setfromoptions) {
    168:       (*st->ops->setfromoptions)(PetscOptionsObject,st);
    169:     }
    170:     PetscObjectProcessOptionsHandlers((PetscObject)st);
    171:   PetscOptionsEnd();
    172:   if (!st->ksp) { STGetKSP(st,&st->ksp); }
    173:   KSPSetFromOptions(st->ksp);
    174:   return(0);
    175: }

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

    183:    Logically Collective on ST

    185:    Input Parameters:
    186: +  st  - the spectral transformation context
    187: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    188:          SUBSET_NONZERO_PATTERN

    190:    Options Database Key:
    191: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
    192:          of 'same' (matrices have the same nonzero pattern), 'different'
    193:          (different nonzero pattern) or 'subset' (pattern is a subset of the
    194:          first one).

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

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

    203:    Level: advanced

    205: .seealso: STSetOperators(), MatAXPY()
    206: @*/
    207: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
    208: {
    212:   switch (str) {
    213:     case SAME_NONZERO_PATTERN:
    214:     case DIFFERENT_NONZERO_PATTERN:
    215:     case SUBSET_NONZERO_PATTERN:
    216:       st->str = str;
    217:       break;
    218:     default:
    219:       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
    220:   }
    221:   return(0);
    222: }

    226: /*@
    227:    STGetMatStructure - Gets the internal MatStructure attribute to
    228:    indicate which is the relation of the sparsity pattern of the matrices.

    230:    Not Collective

    232:    Input Parameters:
    233: .  st  - the spectral transformation context

    235:    Output Parameters:
    236: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
    237:          SUBSET_NONZERO_PATTERN

    239:    Level: advanced

    241: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
    242: @*/
    243: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    244: {
    248:   *str = st->str;
    249:   return(0);
    250: }

    254: /*@
    255:    STSetMatMode - Sets a flag to indicate how the transformed matrices are
    256:    being stored in the spectral transformations.

    258:    Logically Collective on ST

    260:    Input Parameters:
    261: +  st - the spectral transformation context
    262: -  mode - the mode flag, one of ST_MATMODE_COPY,
    263:           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL

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

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

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

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

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

    288:    Level: intermediate

    290: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
    291: @*/
    292: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    293: {
    297:   st->shift_matrix = mode;
    298:   st->setupcalled = 0;
    299:   return(0);
    300: }

    304: /*@
    305:    STGetMatMode - Gets a flag that indicates how the transformed matrices
    306:    are stored in spectral transformations.

    308:    Not Collective

    310:    Input Parameter:
    311: .  st - the spectral transformation context

    313:    Output Parameter:
    314: .  mode - the mode flag

    316:    Level: intermediate

    318: .seealso: STSetMatMode(), STMatMode
    319: @*/
    320: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    321: {
    325:   *mode = st->shift_matrix;
    326:   return(0);
    327: }

    331: /*@
    332:    STSetTransform - Sets a flag to indicate whether the transformed matrices are
    333:    computed or not.

    335:    Logically Collective on ST

    337:    Input Parameters:
    338: +  st  - the spectral transformation context
    339: -  flg - the boolean flag

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

    344:    Notes:
    345:    This flag is intended for the case of polynomial eigenproblems solved
    346:    via linearization. If this flag is off (default) the spectral transformation
    347:    is applied to the linearization (handled by the eigensolver), otherwise
    348:    it is applied to the original problem.

    350:    Level: developer

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

    366: /*@
    367:    STGetTransform - Gets a flag that that indicates whether the transformed
    368:    matrices are computed or not.

    370:    Not Collective

    372:    Input Parameter:
    373: .  st - the spectral transformation context

    375:    Output Parameter:
    376: .  flg - the flag

    378:    Level: developer

    380: .seealso: STSetTransform()
    381: @*/
    382: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
    383: {
    387:   *flg = st->transform;
    388:   return(0);
    389: }