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-2010, 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:   PetscScalar    s;
141:   char           type[256];
142:   PetscTruth     flg;
143:   const char     *mode_list[3] = { "copy", "inplace", "shell" };
144:   const char     *structure_list[3] = { "same", "different", "subset" };


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

161:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
162:     if (flg) { STSetShift(st,s); }

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:   KSPSetFromOptions(st->ksp);

178:   return(0);
179: }

183: /*@
184:    STSetMatStructure - Sets an internal MatStructure attribute to 
185:    indicate which is the relation of the sparsity pattern of the two matrices
186:    A and B constituting the generalized eigenvalue problem. This function
187:    has no effect in the case of standard eigenproblems.

189:    Collective on ST

191:    Input Parameters:
192: +  st  - the spectral transformation context
193: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
194:          SUBSET_NONZERO_PATTERN

196:    Options Database Key:
197: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
198:          of 'same' (A and B have the same nonzero pattern), 'different' (A 
199:          and B have different nonzero pattern) or 'subset' (B's nonzero 
200:          pattern is a subset of A's).

202:    Note:
203:    By default, the sparsity patterns are assumed to be different. If the
204:    patterns are equal or a subset then it is recommended to set this attribute
205:    for efficiency reasons (in particular, for internal MatAXPY() operations).
206:    
207:    Level: advanced

209: .seealso: STSetOperators(), MatAXPY()
210: @*/
211: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
212: {
215:   switch (str) {
216:     case SAME_NONZERO_PATTERN:
217:     case DIFFERENT_NONZERO_PATTERN:
218:     case SUBSET_NONZERO_PATTERN:
219:       st->str = str;
220:       break;
221:     default:
222:       SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
223:   }
224:   return(0);
225: }

229: /*@
230:    STGetMatStructure - Gets the internal MatStructure attribute to 
231:    indicate which is the relation of the sparsity pattern of the two matrices
232:    A and B constituting the generalized eigenvalue problem. This function
233:    has no effect in the case of standard eigenproblems.

235:    Collective on ST

237:    Input Parameters:
238: .  st  - the spectral transformation context

240:    Output Parameters:
241: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
242:          SUBSET_NONZERO_PATTERN

244:    Level: advanced

246: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
247: @*/
248: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
249: {
253:   *str = st->str;
254:   return(0);
255: }

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

263:    Collective on ST

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

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

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

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

284:    With ST_MATMODE_SHELL, the solver works with an implicit shell 
285:    matrix that represents the shifted matrix. This mode is the most efficient 
286:    in creating the shifted matrix but it places serious limitations to the 
287:    linear solves performed in each iteration of the eigensolver (typically,
288:    only interative solvers with Jacobi preconditioning can be used).
289:    
290:    In the case of generalized problems, in the two first modes the matrix
291:    A - s B has to be computed explicitly. The efficiency of this computation 
292:    can be controlled with STSetMatStructure().

294:    Level: intermediate

296: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
297: @*/
298: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
299: {
302:   st->shift_matrix = mode;
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:    Collective on ST

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: {
328:   *mode = st->shift_matrix;
329:   return(0);
330: }