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-2011, Universitat Politecnica de Valencia, Spain

  8:    This file is part of SLEPc.
  9:       
 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 <private/stimpl.h>      /*I "slepcst.h" I*/

 26: PetscBool  STRegisterAllCalled = PETSC_FALSE;
 27: PetscFList 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,const STType type)
 59: {
 60:   PetscErrorCode ierr,(*r)(ST);
 61:   PetscBool      match;


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

 70:    PetscFListFind(STList,((PetscObject)st)->comm,type,PETSC_TRUE,(void (**)(void))&r);
 71:   if (!r) SETERRQ1(((PetscObject)st)->comm,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,const 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(PETSC_NULL); }
136:   PetscOptionsBegin(((PetscObject)st)->comm,((PetscObject)st)->prefix,"Spectral Transformation (ST) Options","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) { STSetShift(st,s); }

151:     PetscOptionsEList("-st_matmode","Shift matrix mode","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
152:     if (flg) { st->shift_matrix = (STMatMode)i; }

154:     PetscOptionsEList("-st_matstructure","Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
155:     if (flg) {
156:       switch (i) {
157:         case 0: STSetMatStructure(st,SAME_NONZERO_PATTERN); break;
158:         case 1: STSetMatStructure(st,DIFFERENT_NONZERO_PATTERN); break;
159:         case 2: STSetMatStructure(st,SUBSET_NONZERO_PATTERN); break;
160:       }
161:     }
162: 
163:     if (st->ops->setfromoptions) {
164:       (*st->ops->setfromoptions)(st);
165:     }
166:     PetscObjectProcessOptionsHandlers((PetscObject)st);
167:   PetscOptionsEnd();
168:   KSPSetFromOptions(st->ksp);
169:   return(0);
170: }

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

179:    Logically Collective on ST

181:    Input Parameters:
182: +  st  - the spectral transformation context
183: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
184:          SUBSET_NONZERO_PATTERN

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

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

197:    This function has no effect in the case of standard eigenproblems.
198:    
199:    Level: advanced

201: .seealso: STSetOperators(), MatAXPY()
202: @*/
203: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
204: {
208:   switch (str) {
209:     case SAME_NONZERO_PATTERN:
210:     case DIFFERENT_NONZERO_PATTERN:
211:     case SUBSET_NONZERO_PATTERN:
212:       st->str = str;
213:       break;
214:     default:
215:       SETERRQ(((PetscObject)st)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
216:   }
217:   return(0);
218: }

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

227:    Not Collective

229:    Input Parameters:
230: .  st  - the spectral transformation context

232:    Output Parameters:
233: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
234:          SUBSET_NONZERO_PATTERN

236:    Note:
237:    This function has no effect in the case of standard eigenproblems.

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 matrix is
256:    being shifted in the shift-and-invert and Cayley 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' or '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 shifted explicitly, e.g. A <- (A - s B). 

273:    With ST_MATMODE_INPLACE, the original matrix A is shifted at 
274:    STSetUp() and unshifted at the end of the computations. With respect to
275:    the previous one, this mode avoids a copy of matrix A. However, a
276:    backdraw 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).
284:    
285:    In the case of generalized problems, in the two first modes the matrix
286:    A - s B has to be computed explicitly. The efficiency of this computation 
287:    can be controlled with STSetMatStructure().

289:    Level: intermediate

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

304: /*@C
305:    STGetMatMode - Gets a flag that indicates how the matrix is being 
306:    shifted in the shift-and-invert and Cayley 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: }