LCOV - code coverage report
Current view: top level - sys/classes/st/interface - stset.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 87 88 98.9 %
Date: 2019-11-15 09:58:42 Functions: 9 9 100.0 %

          Line data    Source code
       1             : /*
       2             :    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       3             :    SLEPc - Scalable Library for Eigenvalue Problem Computations
       4             :    Copyright (c) 2002-2019, Universitat Politecnica de Valencia, Spain
       5             : 
       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             : */
      13             : 
      14             : #include <slepc/private/stimpl.h>      /*I "slepcst.h" I*/
      15             : 
      16             : PetscBool         STRegisterAllCalled = PETSC_FALSE;
      17             : PetscFunctionList STList = 0;
      18             : 
      19             : /*@C
      20             :    STSetType - Builds ST for a particular spectral transformation.
      21             : 
      22             :    Logically Collective on st
      23             : 
      24             :    Input Parameter:
      25             : +  st   - the spectral transformation context.
      26             : -  type - a known type
      27             : 
      28             :    Options Database Key:
      29             : .  -st_type <type> - Sets ST type
      30             : 
      31             :    Use -help for a list of available transformations
      32             : 
      33             :    Notes:
      34             :    See "slepc/include/slepcst.h" for available transformations
      35             : 
      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.
      40             : 
      41             :    Level: beginner
      42             : 
      43             : .seealso: EPSSetType()
      44             : 
      45             : @*/
      46         761 : PetscErrorCode STSetType(ST st,STType type)
      47             : {
      48             :   PetscErrorCode ierr,(*r)(ST);
      49             :   PetscBool      match;
      50             : 
      51         761 :   PetscFunctionBegin;
      52         761 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
      53         761 :   PetscValidCharPointer(type,2);
      54             : 
      55         761 :   ierr = PetscObjectTypeCompare((PetscObject)st,type,&match);CHKERRQ(ierr);
      56         761 :   if (match) PetscFunctionReturn(0);
      57             : 
      58         750 :   ierr =  PetscFunctionListFind(STList,type,&r);CHKERRQ(ierr);
      59         750 :   if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
      60             : 
      61         750 :   if (st->ops->destroy) { ierr = (*st->ops->destroy)(st);CHKERRQ(ierr); }
      62         750 :   ierr = PetscMemzero(st->ops,sizeof(struct _STOps));CHKERRQ(ierr);
      63             : 
      64         750 :   st->state = ST_STATE_INITIAL;
      65         750 :   ierr = PetscObjectChangeTypeName((PetscObject)st,type);CHKERRQ(ierr);
      66         750 :   ierr = (*r)(st);CHKERRQ(ierr);
      67         750 :   PetscFunctionReturn(0);
      68             : }
      69             : 
      70             : /*@C
      71             :    STGetType - Gets the ST type name (as a string) from the ST context.
      72             : 
      73             :    Not Collective
      74             : 
      75             :    Input Parameter:
      76             : .  st - the spectral transformation context
      77             : 
      78             :    Output Parameter:
      79             : .  name - name of the spectral transformation
      80             : 
      81             :    Level: intermediate
      82             : 
      83             : .seealso: STSetType()
      84             : 
      85             : @*/
      86          43 : PetscErrorCode STGetType(ST st,STType *type)
      87             : {
      88          43 :   PetscFunctionBegin;
      89          43 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
      90          43 :   PetscValidPointer(type,2);
      91          43 :   *type = ((PetscObject)st)->type_name;
      92          43 :   PetscFunctionReturn(0);
      93             : }
      94             : 
      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.
      99             : 
     100             :    Collective on st
     101             : 
     102             :    Input Parameter:
     103             : .  st - the spectral transformation context
     104             : 
     105             :    Level: beginner
     106             : @*/
     107         532 : PetscErrorCode STSetFromOptions(ST st)
     108             : {
     109             :   PetscErrorCode ierr;
     110             :   PetscScalar    s;
     111             :   char           type[256];
     112             :   PetscBool      flg;
     113         532 :   const char     *structure_list[3] = {"different","subset","same"};
     114             :   STMatMode      mode;
     115             :   MatStructure   mstr;
     116             : 
     117         532 :   PetscFunctionBegin;
     118         532 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     119         532 :   ierr = STRegisterAll();CHKERRQ(ierr);
     120        1064 :   ierr = PetscObjectOptionsBegin((PetscObject)st);CHKERRQ(ierr);
     121         532 :     ierr = PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);CHKERRQ(ierr);
     122         532 :     if (flg) {
     123         115 :       ierr = STSetType(st,type);CHKERRQ(ierr);
     124         417 :     } else if (!((PetscObject)st)->type_name) {
     125          12 :       ierr = STSetType(st,STSHIFT);CHKERRQ(ierr);
     126             :     }
     127             : 
     128         532 :     ierr = PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);CHKERRQ(ierr);
     129         532 :     if (flg) { ierr = STSetShift(st,s);CHKERRQ(ierr); }
     130             : 
     131         532 :     ierr = PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg);CHKERRQ(ierr);
     132         532 :     if (flg) { ierr = STSetMatMode(st,mode);CHKERRQ(ierr); }
     133             : 
     134         532 :     ierr = PetscOptionsEList("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",structure_list,3,structure_list[st->str],(PetscInt*)&mstr,&flg);CHKERRQ(ierr);
     135         532 :     if (flg) { ierr = STSetMatStructure(st,mstr);CHKERRQ(ierr); }
     136             : 
     137         532 :     ierr = PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&st->transform,&flg);CHKERRQ(ierr);
     138             : 
     139         532 :     if (st->ops->setfromoptions) {
     140           7 :       ierr = (*st->ops->setfromoptions)(PetscOptionsObject,st);CHKERRQ(ierr);
     141             :     }
     142         532 :     ierr = PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);CHKERRQ(ierr);
     143        1064 :   ierr = PetscOptionsEnd();CHKERRQ(ierr);
     144             : 
     145         532 :   if (st->usesksp) {
     146         526 :     ierr = STSetDefaultKSP(st);CHKERRQ(ierr);
     147         526 :     ierr = KSPSetFromOptions(st->ksp);CHKERRQ(ierr);
     148             :   }
     149         532 :   PetscFunctionReturn(0);
     150             : }
     151             : 
     152             : /*@
     153             :    STSetMatStructure - Sets an internal MatStructure attribute to
     154             :    indicate which is the relation of the sparsity pattern of all ST matrices.
     155             : 
     156             :    Logically Collective on st
     157             : 
     158             :    Input Parameters:
     159             : +  st  - the spectral transformation context
     160             : -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
     161             :          SUBSET_NONZERO_PATTERN
     162             : 
     163             :    Options Database Key:
     164             : .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
     165             :          of 'same' (matrices have the same nonzero pattern), 'different'
     166             :          (different nonzero pattern) or 'subset' (pattern is a subset of the
     167             :          first one).
     168             : 
     169             :    Notes:
     170             :    By default, the sparsity patterns are assumed to be different. If the
     171             :    patterns are equal or a subset then it is recommended to set this attribute
     172             :    for efficiency reasons (in particular, for internal MatAXPY() operations).
     173             : 
     174             :    This function has no effect in the case of standard eigenproblems.
     175             : 
     176             :    Level: advanced
     177             : 
     178             : .seealso: STSetMatrices(), MatAXPY()
     179             : @*/
     180           2 : PetscErrorCode STSetMatStructure(ST st,MatStructure str)
     181             : {
     182           2 :   PetscFunctionBegin;
     183           2 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     184           4 :   PetscValidLogicalCollectiveEnum(st,str,2);
     185           2 :   switch (str) {
     186             :     case SAME_NONZERO_PATTERN:
     187             :     case DIFFERENT_NONZERO_PATTERN:
     188             :     case SUBSET_NONZERO_PATTERN:
     189           2 :       st->str = str;
     190             :       break;
     191             :     default:
     192           0 :       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
     193             :   }
     194           4 :   PetscFunctionReturn(0);
     195             : }
     196             : 
     197             : /*@
     198             :    STGetMatStructure - Gets the internal MatStructure attribute to
     199             :    indicate which is the relation of the sparsity pattern of the matrices.
     200             : 
     201             :    Not Collective
     202             : 
     203             :    Input Parameters:
     204             : .  st  - the spectral transformation context
     205             : 
     206             :    Output Parameters:
     207             : .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
     208             :          SUBSET_NONZERO_PATTERN
     209             : 
     210             :    Level: advanced
     211             : 
     212             : .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
     213             : @*/
     214         300 : PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
     215             : {
     216         300 :   PetscFunctionBegin;
     217         300 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     218         300 :   PetscValidPointer(str,2);
     219         300 :   *str = st->str;
     220         300 :   PetscFunctionReturn(0);
     221             : }
     222             : 
     223             : /*@
     224             :    STSetMatMode - Sets a flag to indicate how the transformed matrices are
     225             :    being stored in the spectral transformations.
     226             : 
     227             :    Logically Collective on st
     228             : 
     229             :    Input Parameters:
     230             : +  st - the spectral transformation context
     231             : -  mode - the mode flag, one of ST_MATMODE_COPY,
     232             :           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL
     233             : 
     234             :    Options Database Key:
     235             : .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
     236             :           'copy', 'inplace', 'shell' (see explanation below).
     237             : 
     238             :    Notes:
     239             :    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
     240             :    this copy is modified explicitly, e.g. A <- (A - s B).
     241             : 
     242             :    With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
     243             :    and changes are reverted at the end of the computations. With respect to
     244             :    the previous one, this mode avoids a copy of matrix A. However, a
     245             :    drawback is that the recovered matrix might be slightly different
     246             :    from the original one (due to roundoff).
     247             : 
     248             :    With ST_MATMODE_SHELL, the solver works with an implicit shell
     249             :    matrix that represents the shifted matrix. This mode is the most efficient
     250             :    in creating the shifted matrix but it places serious limitations to the
     251             :    linear solves performed in each iteration of the eigensolver (typically,
     252             :    only interative solvers with Jacobi preconditioning can be used).
     253             : 
     254             :    In the two first modes the efficiency of the computation
     255             :    can be controlled with STSetMatStructure().
     256             : 
     257             :    Level: intermediate
     258             : 
     259             : .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
     260             : @*/
     261          36 : PetscErrorCode STSetMatMode(ST st,STMatMode mode)
     262             : {
     263          36 :   PetscFunctionBegin;
     264          36 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     265          72 :   PetscValidLogicalCollectiveEnum(st,mode,2);
     266          36 :   if (st->matmode != mode) {
     267          31 :     st->matmode = mode;
     268          31 :     st->state = ST_STATE_INITIAL;
     269             :   }
     270          36 :   PetscFunctionReturn(0);
     271             : }
     272             : 
     273             : /*@
     274             :    STGetMatMode - Gets a flag that indicates how the transformed matrices
     275             :    are stored in spectral transformations.
     276             : 
     277             :    Not Collective
     278             : 
     279             :    Input Parameter:
     280             : .  st - the spectral transformation context
     281             : 
     282             :    Output Parameter:
     283             : .  mode - the mode flag
     284             : 
     285             :    Level: intermediate
     286             : 
     287             : .seealso: STSetMatMode(), STMatMode
     288             : @*/
     289         534 : PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
     290             : {
     291         534 :   PetscFunctionBegin;
     292         534 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     293         534 :   PetscValidPointer(mode,2);
     294         534 :   *mode = st->matmode;
     295         534 :   PetscFunctionReturn(0);
     296             : }
     297             : 
     298             : /*@
     299             :    STSetTransform - Sets a flag to indicate whether the transformed matrices are
     300             :    computed or not.
     301             : 
     302             :    Logically Collective on st
     303             : 
     304             :    Input Parameters:
     305             : +  st  - the spectral transformation context
     306             : -  flg - the boolean flag
     307             : 
     308             :    Options Database Key:
     309             : .  -st_transform <bool> - Activate/deactivate the computation of matrices.
     310             : 
     311             :    Notes:
     312             :    This flag is intended for the case of polynomial eigenproblems solved
     313             :    via linearization. If this flag is off (default) the spectral transformation
     314             :    is applied to the linearization (handled by the eigensolver), otherwise
     315             :    it is applied to the original problem.
     316             : 
     317             :    Level: developer
     318             : 
     319             : .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
     320             : @*/
     321         617 : PetscErrorCode STSetTransform(ST st,PetscBool flg)
     322             : {
     323         617 :   PetscFunctionBegin;
     324         617 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     325        1234 :   PetscValidLogicalCollectiveBool(st,flg,2);
     326         617 :   if (st->transform != flg) {
     327         434 :     st->transform = flg;
     328         434 :     st->state = ST_STATE_INITIAL;
     329             :   }
     330         617 :   PetscFunctionReturn(0);
     331             : }
     332             : 
     333             : /*@
     334             :    STGetTransform - Gets a flag that that indicates whether the transformed
     335             :    matrices are computed or not.
     336             : 
     337             :    Not Collective
     338             : 
     339             :    Input Parameter:
     340             : .  st - the spectral transformation context
     341             : 
     342             :    Output Parameter:
     343             : .  flg - the flag
     344             : 
     345             :    Level: developer
     346             : 
     347             : .seealso: STSetTransform()
     348             : @*/
     349       10337 : PetscErrorCode STGetTransform(ST st,PetscBool *flg)
     350             : {
     351       10337 :   PetscFunctionBegin;
     352       10337 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     353       10337 :   PetscValidBoolPointer(flg,2);
     354       10337 :   *flg = st->transform;
     355       10337 :   PetscFunctionReturn(0);
     356             : }
     357             : 

Generated by: LCOV version 1.13