Date: 2013-09-02T10:05:57+00:00

Actual source code: stset.c

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

      4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      6:    Copyright (c) 2002-2013, 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: intermediate

     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:   if (!STRegisterAllCalled) { STRegisterAll(); }
    136:   PetscObjectOptionsBegin((PetscObject)st);
    137:     PetscOptionsList("-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","Shift matrix mode","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:     if (st->ops->setfromoptions) {
    166:       (*st->ops->setfromoptions)(st);
    167:     }
    168:     PetscObjectProcessOptionsHandlers((PetscObject)st);
    169:   PetscOptionsEnd();
    170:   if (!st->ksp) { STGetKSP(st,&st->ksp); }
    171:   KSPSetFromOptions(st->ksp);
    172:   return(0);
    173: }

    177: /*@
    178:    STSetMatStructure - Sets an internal MatStructure attribute to
    179:    indicate which is the relation of the sparsity pattern of the two matrices
    180:    A and B constituting the generalized eigenvalue problem.

    182:    Logically Collective on ST

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

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

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

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

    202:    Level: advanced

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

    225: /*@
    226:    STGetMatStructure - Gets the internal MatStructure attribute to
    227:    indicate which is the relation of the sparsity pattern of the two matrices
    228:    A and B constituting the generalized eigenvalue problem.

    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:    Note:
    240:    This function has no effect in the case of standard eigenproblems.

    242:    Level: advanced

    244: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
    245: @*/
    246: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
    247: {
    251:   *str = st->str;
    252:   return(0);
    253: }

    257: /*@
    258:    STSetMatMode - Sets a flag to indicate how the matrix is
    259:    being shifted in the shift-and-invert and Cayley spectral transformations.

    261:    Logically Collective on ST

    263:    Input Parameters:
    264: +  st - the spectral transformation context
    265: -  mode - the mode flag, one of ST_MATMODE_COPY,
    266:           ST_MATMODE_INPLACE or ST_MATMODE_SHELL

    268:    Options Database Key:
    269: .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
    270:           'copy', 'inplace' or 'shell' (see explanation below).

    272:    Notes:
    273:    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
    274:    this copy is shifted explicitly, e.g. A <- (A - s B).

    276:    With ST_MATMODE_INPLACE, the original matrix A is shifted at
    277:    STSetUp() and unshifted at the end of the computations. With respect to
    278:    the previous one, this mode avoids a copy of matrix A. However, a
    279:    backdraw is that the recovered matrix might be slightly different
    280:    from the original one (due to roundoff).

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

    288:    In the case of generalized problems, in the two first modes the matrix
    289:    A - s B has to be computed explicitly. The efficiency of this computation
    290:    can be controlled with STSetMatStructure().

    292:    Level: intermediate

    294: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
    295: @*/
    296: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
    297: {
    301:   st->shift_matrix = mode;
    302:   st->setupcalled = 0;
    303:   return(0);
    304: }

    308: /*@C
    309:    STGetMatMode - Gets a flag that indicates how the matrix is being
    310:    shifted in the shift-and-invert and Cayley spectral transformations.

    312:    Not Collective

    314:    Input Parameter:
    315: .  st - the spectral transformation context

    317:    Output Parameter:
    318: .  mode - the mode flag

    320:    Level: intermediate

    322: .seealso: STSetMatMode(), STMatMode
    323: @*/
    324: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
    325: {
    329:   *mode = st->shift_matrix;
    330:   return(0);
    331: }