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-2009, Universidad 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
 25: #include "petscsys.h"

 27: /*
 28:    Contains the list of registered ST routines
 29: */
 30: PetscFList STList = 0;

 34: /*@C
 35:    STSetType - Builds ST for a particular spectral transformation.

 37:    Collective on ST

 39:    Input Parameter:
 40: +  st   - the spectral transformation context.
 41: -  type - a known type

 43:    Options Database Key:
 44: .  -st_type <type> - Sets ST type

 46:    Use -help for a list of available transformations

 48:    Notes:
 49:    See "slepc/include/slepcst.h" for available transformations 

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

 56:    Level: intermediate

 58: .seealso: EPSSetType()

 60: @*/
 61: PetscErrorCode STSetType(ST st,const STType type)
 62: {
 63:   PetscErrorCode ierr,(*r)(ST);
 64:   PetscTruth match;


 70:   PetscTypeCompare((PetscObject)st,type,&match);
 71:   if (match) return(0);

 73:   if (st->ops->destroy) { (*st->ops->destroy)(st);}
 74:   PetscFListDestroy(&((PetscObject)st)->qlist);
 75:   st->data        = 0;
 76:   st->setupcalled = 0;

 78:   /* Determine the STCreateXXX routine for a particular type */
 79:    PetscFListFind(STList, ((PetscObject)st)->comm, type,(void (**)(void)) &r );
 80:   if (!r) SETERRQ1(1,"Unable to find requested ST type %s",type);
 81:   PetscFree(st->data);

 83:   PetscMemzero(st->ops,sizeof(struct _STOps));

 85:   /* Call the STCreateXXX routine for this particular type */
 86:   (*r)(st);

 88:   PetscObjectChangeTypeName((PetscObject)st,type);
 89:   return(0);
 90: }

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

 97:    Not Collective

 99:    Input Parameter:
100: .  st - the spectral transformation context

102:    Output Parameter:
103: .  name - name of the spectral transformation 

105:    Level: intermediate

107: .seealso: STSetType()

109: @*/
110: PetscErrorCode STGetType(ST st,const STType *type)
111: {
115:   *type = ((PetscObject)st)->type_name;
116:   return(0);
117: }

121: /*@
122:    STSetFromOptions - Sets ST options from the options database.
123:    This routine must be called before STSetUp() if the user is to be
124:    allowed to set the type of transformation.

126:    Collective on ST

128:    Input Parameter:
129: .  st - the spectral transformation context

131:    Level: beginner

133: .seealso: 

135: @*/
136: PetscErrorCode STSetFromOptions(ST st)
137: {
139:   PetscInt       i;
140:   char           type[256];
141:   PetscTruth     flg;
142:   const char     *mode_list[3] = { "copy", "inplace", "shell" };
143:   const char     *structure_list[3] = { "same", "different", "subset" };
144:   PC             pc;
145:   const char     *pctype;


150:   PetscOptionsBegin(((PetscObject)st)->comm,((PetscObject)st)->prefix,"Spectral Transformation (ST) Options","ST");
151:     PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
152:     if (flg) {
153:       STSetType(st,type);
154:     }
155:     /*
156:       Set the type if it was never set.
157:     */
158:     if (!((PetscObject)st)->type_name) {
159:       STSetType(st,STSHIFT);
160:     }

162:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&st->sigma,PETSC_NULL);

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

167:     PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
168:     if (flg) { st->str = (MatStructure)i; }
169: 
170:     if (st->ops->setfromoptions) {
171:       (*st->ops->setfromoptions)(st);
172:     }

174:   PetscOptionsEnd();

176:   if (st->ksp) {
177:     KSPGetPC(st->ksp,&pc);
178:     PCGetType(pc,&pctype);
179:     if (!pctype) {
180:       if (st->shift_matrix == STMATMODE_SHELL) {
181:         /* in shell mode use GMRES with Jacobi as the default */
182:         KSPSetType(st->ksp,KSPGMRES);
183:         PCSetType(pc,PCJACOBI);
184:       } else {
185:         /* use direct solver as default */
186:         KSPSetType(st->ksp,KSPPREONLY);
187:         PCSetType(pc,PCREDUNDANT);
188:       }
189:     }
190:     KSPSetFromOptions(st->ksp);
191:   }

193:   return(0);
194: }

198: /*@
199:    STSetMatStructure - Sets an internal MatStructure attribute to 
200:    indicate which is the relation of the sparsity pattern of the two matrices
201:    A and B constituting the generalized eigenvalue problem. This function
202:    has no effect in the case of standard eigenproblems.

204:    Collective on ST

206:    Input Parameters:
207: +  st  - the spectral transformation context
208: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
209:          SUBSET_NONZERO_PATTERN

211:    Options Database Key:
212: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
213:          of 'same' (A and B have the same nonzero pattern), 'different' (A 
214:          and B have different nonzero pattern) or 'subset' (B's nonzero 
215:          pattern is a subset of A's).

217:    Note:
218:    By default, the sparsity patterns are assumed to be different. If the
219:    patterns are equal or a subset then it is recommended to set this attribute
220:    for efficiency reasons (in particular, for internal MatAXPY() operations).
221:    
222:    Level: advanced

224: .seealso: STSetOperators(), MatAXPY()
225: @*/
226: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
227: {
230:   switch (str) {
231:     case SAME_NONZERO_PATTERN:
232:     case DIFFERENT_NONZERO_PATTERN:
233:     case SUBSET_NONZERO_PATTERN:
234:       st->str = str;
235:       break;
236:     default:
237:       SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
238:   }
239:   return(0);
240: }

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

248:    Collective on ST

250:    Input Parameters:
251: +  st - the spectral transformation context
252: -  mode - the mode flag, one of STMATMODE_COPY, 
253:           STMATMODE_INPLACE or STMATMODE_SHELL

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

259:    Notes:
260:    By default (STMATMODE_COPY), a copy of matrix A is made and then 
261:    this copy is shifted explicitly, e.g. A <- (A - s B). 

263:    With STMATMODE_INPLACE, the original matrix A is shifted at 
264:    STSetUp() and unshifted at the end of the computations. With respect to
265:    the previous one, this mode avoids a copy of matrix A. However, a
266:    backdraw is that the recovered matrix might be slightly different 
267:    from the original one (due to roundoff).

269:    With STMATMODE_SHELL, the solver works with an implicit shell 
270:    matrix that represents the shifted matrix. This mode is the most efficient 
271:    in creating the shifted matrix but it places serious limitations to the 
272:    linear solves performed in each iteration of the eigensolver (typically,
273:    only interative solvers with Jacobi preconditioning can be used).
274:    
275:    In the case of generalized problems, in the two first modes the matrix
276:    A - s B has to be computed explicitly. The efficiency of this computation 
277:    can be controlled with STSetMatStructure().

279:    Level: intermediate

281: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
282: @*/
283: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
284: {
287:   st->shift_matrix = mode;
288:   return(0);
289: }

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

297:    Collective on ST

299:    Input Parameter:
300: .  st - the spectral transformation context

302:    Output Parameter:
303: .  mode - the mode flag

305:    Level: intermediate

307: .seealso: STSetMatMode(), STMatMode
308: @*/
309: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
310: {
313:   *mode = st->shift_matrix;
314:   return(0);
315: }