LCOV - code coverage report
Current view: top level - sys/classes/st/interface - stset.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 86 87 98.9 %
Date: 2019-09-16 06:01:52 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         751 : PetscErrorCode STSetType(ST st,STType type)
      47             : {
      48             :   PetscErrorCode ierr,(*r)(ST);
      49             :   PetscBool      match;
      50             : 
      51         751 :   PetscFunctionBegin;
      52         751 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
      53         751 :   PetscValidCharPointer(type,2);
      54             : 
      55         751 :   ierr = PetscObjectTypeCompare((PetscObject)st,type,&match);CHKERRQ(ierr);
      56         751 :   if (match) PetscFunctionReturn(0);
      57             : 
      58         740 :   ierr =  PetscFunctionListFind(STList,type,&r);CHKERRQ(ierr);
      59         740 :   if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
      60             : 
      61         740 :   if (st->ops->destroy) { ierr = (*st->ops->destroy)(st);CHKERRQ(ierr); }
      62         740 :   ierr = PetscMemzero(st->ops,sizeof(struct _STOps));CHKERRQ(ierr);
      63             : 
      64         740 :   st->state = ST_STATE_INITIAL;
      65         740 :   ierr = PetscObjectChangeTypeName((PetscObject)st,type);CHKERRQ(ierr);
      66         740 :   ierr = (*r)(st);CHKERRQ(ierr);
      67         740 :   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          42 : PetscErrorCode STGetType(ST st,STType *type)
      87             : {
      88          42 :   PetscFunctionBegin;
      89          42 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
      90          42 :   PetscValidPointer(type,2);
      91          42 :   *type = ((PetscObject)st)->type_name;
      92          42 :   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         523 : PetscErrorCode STSetFromOptions(ST st)
     108             : {
     109             :   PetscErrorCode ierr;
     110             :   PetscScalar    s;
     111             :   char           type[256];
     112             :   PetscBool      flg;
     113         523 :   const char     *structure_list[3] = {"different","subset","same"};
     114             :   STMatMode      mode;
     115             :   MatStructure   mstr;
     116             : 
     117         523 :   PetscFunctionBegin;
     118         523 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     119         523 :   ierr = STRegisterAll();CHKERRQ(ierr);
     120        1046 :   ierr = PetscObjectOptionsBegin((PetscObject)st);CHKERRQ(ierr);
     121         523 :     ierr = PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);CHKERRQ(ierr);
     122         523 :     if (flg) {
     123         115 :       ierr = STSetType(st,type);CHKERRQ(ierr);
     124         408 :     } else if (!((PetscObject)st)->type_name) {
     125          12 :       ierr = STSetType(st,STSHIFT);CHKERRQ(ierr);
     126             :     }
     127             : 
     128         523 :     ierr = PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);CHKERRQ(ierr);
     129         523 :     if (flg) { ierr = STSetShift(st,s);CHKERRQ(ierr); }
     130             : 
     131         523 :     ierr = PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->shift_matrix,(PetscEnum*)&mode,&flg);CHKERRQ(ierr);
     132         523 :     if (flg) { ierr = STSetMatMode(st,mode);CHKERRQ(ierr); }
     133             : 
     134         523 :     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         523 :     if (flg) { ierr = STSetMatStructure(st,mstr);CHKERRQ(ierr); }
     136             : 
     137         523 :     ierr = PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&st->transform,&flg);CHKERRQ(ierr);
     138             : 
     139         523 :     if (st->ops->setfromoptions) {
     140           7 :       ierr = (*st->ops->setfromoptions)(PetscOptionsObject,st);CHKERRQ(ierr);
     141             :     }
     142         523 :     ierr = PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);CHKERRQ(ierr);
     143        1046 :   ierr = PetscOptionsEnd();CHKERRQ(ierr);
     144             : 
     145         523 :   ierr = STSetDefaultKSP(st);CHKERRQ(ierr);
     146         523 :   ierr = KSPSetFromOptions(st->ksp);CHKERRQ(ierr);
     147         523 :   PetscFunctionReturn(0);
     148             : }
     149             : 
     150             : /*@
     151             :    STSetMatStructure - Sets an internal MatStructure attribute to
     152             :    indicate which is the relation of the sparsity pattern of all ST matrices.
     153             : 
     154             :    Logically Collective on st
     155             : 
     156             :    Input Parameters:
     157             : +  st  - the spectral transformation context
     158             : -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
     159             :          SUBSET_NONZERO_PATTERN
     160             : 
     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) or 'subset' (pattern is a subset of the
     165             :          first one).
     166             : 
     167             :    Notes:
     168             :    By default, the sparsity patterns are assumed to be different. If the
     169             :    patterns are equal or a subset then it is recommended to set this attribute
     170             :    for efficiency reasons (in particular, for internal MatAXPY() operations).
     171             : 
     172             :    This function has no effect in the case of standard eigenproblems.
     173             : 
     174             :    Level: advanced
     175             : 
     176             : .seealso: STSetMatrices(), MatAXPY()
     177             : @*/
     178           2 : PetscErrorCode STSetMatStructure(ST st,MatStructure str)
     179             : {
     180           2 :   PetscFunctionBegin;
     181           2 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     182           4 :   PetscValidLogicalCollectiveEnum(st,str,2);
     183           2 :   switch (str) {
     184             :     case SAME_NONZERO_PATTERN:
     185             :     case DIFFERENT_NONZERO_PATTERN:
     186             :     case SUBSET_NONZERO_PATTERN:
     187           2 :       st->str = str;
     188             :       break;
     189             :     default:
     190           0 :       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
     191             :   }
     192           4 :   PetscFunctionReturn(0);
     193             : }
     194             : 
     195             : /*@
     196             :    STGetMatStructure - Gets the internal MatStructure attribute to
     197             :    indicate which is the relation of the sparsity pattern of the matrices.
     198             : 
     199             :    Not Collective
     200             : 
     201             :    Input Parameters:
     202             : .  st  - the spectral transformation context
     203             : 
     204             :    Output Parameters:
     205             : .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
     206             :          SUBSET_NONZERO_PATTERN
     207             : 
     208             :    Level: advanced
     209             : 
     210             : .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
     211             : @*/
     212         300 : PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
     213             : {
     214         300 :   PetscFunctionBegin;
     215         300 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     216         300 :   PetscValidPointer(str,2);
     217         300 :   *str = st->str;
     218         300 :   PetscFunctionReturn(0);
     219             : }
     220             : 
     221             : /*@
     222             :    STSetMatMode - Sets a flag to indicate how the transformed matrices are
     223             :    being stored in the spectral transformations.
     224             : 
     225             :    Logically Collective on st
     226             : 
     227             :    Input Parameters:
     228             : +  st - the spectral transformation context
     229             : -  mode - the mode flag, one of ST_MATMODE_COPY,
     230             :           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL
     231             : 
     232             :    Options Database Key:
     233             : .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
     234             :           'copy', 'inplace', 'shell' (see explanation below).
     235             : 
     236             :    Notes:
     237             :    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
     238             :    this copy is modified explicitly, e.g. A <- (A - s B).
     239             : 
     240             :    With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
     241             :    and changes are reverted at the end of the computations. With respect to
     242             :    the previous one, this mode avoids a copy of matrix A. However, a
     243             :    drawback is that the recovered matrix might be slightly different
     244             :    from the original one (due to roundoff).
     245             : 
     246             :    With ST_MATMODE_SHELL, the solver works with an implicit shell
     247             :    matrix that represents the shifted matrix. This mode is the most efficient
     248             :    in creating the shifted matrix but it places serious limitations to the
     249             :    linear solves performed in each iteration of the eigensolver (typically,
     250             :    only interative solvers with Jacobi preconditioning can be used).
     251             : 
     252             :    In the two first modes the efficiency of the computation
     253             :    can be controlled with STSetMatStructure().
     254             : 
     255             :    Level: intermediate
     256             : 
     257             : .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
     258             : @*/
     259          36 : PetscErrorCode STSetMatMode(ST st,STMatMode mode)
     260             : {
     261          36 :   PetscFunctionBegin;
     262          36 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     263          72 :   PetscValidLogicalCollectiveEnum(st,mode,2);
     264          36 :   if (st->shift_matrix != mode) {
     265          31 :     st->shift_matrix = mode;
     266          31 :     st->state = ST_STATE_INITIAL;
     267             :   }
     268          36 :   PetscFunctionReturn(0);
     269             : }
     270             : 
     271             : /*@
     272             :    STGetMatMode - Gets a flag that indicates how the transformed matrices
     273             :    are stored in spectral transformations.
     274             : 
     275             :    Not Collective
     276             : 
     277             :    Input Parameter:
     278             : .  st - the spectral transformation context
     279             : 
     280             :    Output Parameter:
     281             : .  mode - the mode flag
     282             : 
     283             :    Level: intermediate
     284             : 
     285             : .seealso: STSetMatMode(), STMatMode
     286             : @*/
     287         516 : PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
     288             : {
     289         516 :   PetscFunctionBegin;
     290         516 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     291         516 :   PetscValidPointer(mode,2);
     292         516 :   *mode = st->shift_matrix;
     293         516 :   PetscFunctionReturn(0);
     294             : }
     295             : 
     296             : /*@
     297             :    STSetTransform - Sets a flag to indicate whether the transformed matrices are
     298             :    computed or not.
     299             : 
     300             :    Logically Collective on st
     301             : 
     302             :    Input Parameters:
     303             : +  st  - the spectral transformation context
     304             : -  flg - the boolean flag
     305             : 
     306             :    Options Database Key:
     307             : .  -st_transform <bool> - Activate/deactivate the computation of matrices.
     308             : 
     309             :    Notes:
     310             :    This flag is intended for the case of polynomial eigenproblems solved
     311             :    via linearization. If this flag is off (default) the spectral transformation
     312             :    is applied to the linearization (handled by the eigensolver), otherwise
     313             :    it is applied to the original problem.
     314             : 
     315             :    Level: developer
     316             : 
     317             : .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
     318             : @*/
     319         596 : PetscErrorCode STSetTransform(ST st,PetscBool flg)
     320             : {
     321         596 :   PetscFunctionBegin;
     322         596 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     323        1192 :   PetscValidLogicalCollectiveBool(st,flg,2);
     324         596 :   if (st->transform != flg) {
     325         423 :     st->transform = flg;
     326         423 :     st->state = ST_STATE_INITIAL;
     327             :   }
     328         596 :   PetscFunctionReturn(0);
     329             : }
     330             : 
     331             : /*@
     332             :    STGetTransform - Gets a flag that that indicates whether the transformed
     333             :    matrices are computed or not.
     334             : 
     335             :    Not Collective
     336             : 
     337             :    Input Parameter:
     338             : .  st - the spectral transformation context
     339             : 
     340             :    Output Parameter:
     341             : .  flg - the flag
     342             : 
     343             :    Level: developer
     344             : 
     345             : .seealso: STSetTransform()
     346             : @*/
     347       10341 : PetscErrorCode STGetTransform(ST st,PetscBool *flg)
     348             : {
     349       10341 :   PetscFunctionBegin;
     350       10341 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     351       10341 :   PetscValidBoolPointer(flg,2);
     352       10341 :   *flg = st->transform;
     353       10341 :   PetscFunctionReturn(0);
     354             : }
     355             : 

Generated by: LCOV version 1.13