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-2007, Universidad Politecnica de Valencia, Spain

  8:       This file is part of SLEPc. See the README file for conditions of use
  9:       and additional information.
 10:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 11: */

 13:  #include src/st/stimpl.h
 14: #include "petscsys.h"

 16: /*
 17:    Contains the list of registered ST routines
 18: */
 19: PetscFList STList = 0;

 23: /*@C
 24:    STSetType - Builds ST for a particular spectral transformation.

 26:    Collective on ST

 28:    Input Parameter:
 29: +  st   - the spectral transformation context.
 30: -  type - a known type

 32:    Options Database Key:
 33: .  -st_type <type> - Sets ST type

 35:    Use -help for a list of available transformations

 37:    Notes:
 38:    See "slepc/include/slepcst.h" for available transformations 

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

 45:    Level: intermediate

 47: .seealso: EPSSetType()

 49: @*/
 50: PetscErrorCode STSetType(ST st,STType type)
 51: {
 52:   PetscErrorCode ierr,(*r)(ST);
 53:   PetscTruth match;


 59:   PetscTypeCompare((PetscObject)st,type,&match);
 60:   if (match) return(0);

 62:   if (st->ops->destroy) { (*st->ops->destroy)(st);}
 63:   PetscFListDestroy(&st->qlist);
 64:   st->data        = 0;
 65:   st->setupcalled = 0;

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

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

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

 77:   PetscObjectChangeTypeName((PetscObject)st,type);
 78:   return(0);
 79: }

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

 86:    Not Collective

 88:    Input Parameter:
 89: .  st - the spectral transformation context

 91:    Output Parameter:
 92: .  name - name of the spectral transformation 

 94:    Level: intermediate

 96: .seealso: STSetType()

 98: @*/
 99: PetscErrorCode STGetType(ST st,STType *meth)
100: {
102:   *meth = (STType) st->type_name;
103:   return(0);
104: }

108: /*@
109:    STSetFromOptions - Sets ST options from the options database.
110:    This routine must be called before STSetUp() if the user is to be
111:    allowed to set the type of transformation.

113:    Collective on ST

115:    Input Parameter:
116: .  st - the spectral transformation context

118:    Level: beginner

120: .seealso: 

122: @*/
123: PetscErrorCode STSetFromOptions(ST st)
124: {
126:   PetscInt       i;
127:   char           type[256];
128:   PetscTruth     flg;
129:   const char     *mode_list[3] = { "copy", "inplace", "shell" };
130:   const char     *structure_list[3] = { "same", "different", "subset" };
131:   PC             pc;


136:   PetscOptionsBegin(st->comm,st->prefix,"Spectral Transformation (ST) Options","ST");
137:     PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(st->type_name?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 (!st->type_name) {
145:       STSetType(st,STSHIFT);
146:     }

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

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

153:     PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
154:     if (flg) { st->str = (MatStructure)i; }
155: 
156:     if (st->ops->setfromoptions) {
157:       (*st->ops->setfromoptions)(st);
158:     }

160:   PetscOptionsEnd();

162:   if (st->ksp) {
163:     if (st->shift_matrix == STMATMODE_SHELL) {
164:       /* if shift_mat is set then the default preconditioner is ILU,
165:          otherwise set Jacobi as the default */
166:       KSPGetPC(st->ksp,&pc);
167:       PCSetType(pc,PCJACOBI);
168:     }
169:     KSPSetFromOptions(st->ksp);
170:   }

172:   return(0);
173: }

177: /*@
178:    STSetMatStructure - Sets an internal MatStructure attribute to 
179:    indicate which is the relation of the sparsity pattern of the two matrices
180:    A and B constituting the generalized eigenvalue problem. This function
181:    has no effect in the case of standard eigenproblems.

183:    Collective on ST

185:    Input Parameters:
186: +  st  - the spectral transformation context
187: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
188:          SUBSET_NONZERO_PATTERN

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

196:    Note:
197:    By default, the sparsity patterns are assumed to be different. If the
198:    patterns are equal or a subset then it is recommended to set this attribute
199:    for efficiency reasons (in particular, for internal MatAXPY() operations).
200:    
201:    Level: advanced

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

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

227:    Collective on ST

229:    Input Parameters:
230: +  st - the spectral transformation context
231: -  mode - the mode flag, one of STMATMODE_COPY, 
232:           STMATMODE_INPLACE or STMATMODE_SHELL

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

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

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

248:    With STMATMODE_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 case of generalized problems, in the two first modes the matrix
255:    A - s B has to be computed explicitly. The efficiency of this computation 
256:    can be controlled with STSetMatStructure().

258:    Level: intermediate

260: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
261: @*/
262: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
263: {
266:   st->shift_matrix = mode;
267:   return(0);
268: }

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

276:    Collective on ST

278:    Input Parameter:
279: .  st - the spectral transformation context

281:    Output Parameter:
282: .  mode - the mode flag

284:    Level: intermediate

286: .seealso: STSetMatMode(), STMatMode
287: @*/
288: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
289: {
292:   *mode = st->shift_matrix;
293:   return(0);
294: }