Actual source code: stset.c

  2: /*
  3:     Routines to set ST methods and options.
  4: */

 6:  #include src/st/stimpl.h
  7: #include "petscsys.h"

  9: PetscTruth STRegisterAllCalled = PETSC_FALSE;
 10: /*
 11:    Contains the list of registered EPS routines
 12: */
 13: PetscFList STList = 0;

 17: /*@C
 18:    STSetType - Builds ST for a particular spectral transformation.

 20:    Collective on ST

 22:    Input Parameter:
 23: +  st   - the spectral transformation context.
 24: -  type - a known type

 26:    Options Database Key:
 27: .  -st_type <type> - Sets ST type

 29:    Use -help for a list of available transformations

 31:    Notes:
 32:    See "slepc/include/slepcst.h" for available transformations 

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

 39:    Level: intermediate

 41: .seealso: EPSSetType()

 43: @*/
 44: PetscErrorCode STSetType(ST st,STType type)
 45: {
 46:   PetscErrorCode ierr,(*r)(ST);
 47:   PetscTruth match;


 53:   PetscTypeCompare((PetscObject)st,type,&match);
 54:   if (match) return(0);

 56:   if (st->ops->destroy) { (*st->ops->destroy)(st);}
 57:   PetscFListDestroy(&st->qlist);
 58:   st->data        = 0;
 59:   st->setupcalled = 0;

 61:   /* Get the function pointers for the method requested */
 62:   if (!STRegisterAllCalled) {STRegisterAll(0); }

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

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

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

 74:   PetscObjectChangeTypeName((PetscObject)st,type);
 75:   return(0);
 76: }

 80: /*@C
 81:    STRegisterDestroy - Frees the list of spectral transformations that were
 82:    registered by STRegisterDynamic().

 84:    Not Collective

 86:    Level: advanced

 88: .seealso: STRegisterAll(), STRegisterAll()

 90: @*/
 91: PetscErrorCode STRegisterDestroy(void)
 92: {
 93:   PetscErrorCode ierr;

 96:   if (STList) {
 97:     PetscFListDestroy(&STList);
 98:     STList = 0;
 99:   }
100:   STRegisterAllCalled = PETSC_FALSE;
101:   return(0);
102: }

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

109:    Not Collective

111:    Input Parameter:
112: .  st - the spectral transformation context

114:    Output Parameter:
115: .  name - name of the spectral transformation 

117:    Level: intermediate

119: .seealso: STSetType()

121: @*/
122: PetscErrorCode STGetType(ST st,STType *meth)
123: {
125:   *meth = (STType) st->type_name;
126:   return(0);
127: }

131: /*@
132:    STSetFromOptions - Sets ST options from the options database.
133:    This routine must be called before STSetUp() if the user is to be
134:    allowed to set the type of transformation.

136:    Collective on ST

138:    Input Parameter:
139: .  st - the spectral transformation context

141:    Level: beginner

143: .seealso: 

145: @*/
146: PetscErrorCode STSetFromOptions(ST st)
147: {
148:   PetscErrorCode ierr;
149:   int            i;
150:   char           type[256];
151:   PetscTruth     flg;
152:   const char     *mode_list[3] = { "copy", "inplace", "shell" };
153:   const char     *structure_list[3] = { "same", "different", "subset" };
154:   PC             pc;


159:   if (!STRegisterAllCalled) {STRegisterAll(PETSC_NULL);}
160:   PetscOptionsBegin(st->comm,st->prefix,"Spectral Transformation (ST) Options","ST");
161:     PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(st->type_name?st->type_name:STSHIFT),type,256,&flg);
162:     if (flg) {
163:       STSetType(st,type);
164:     }
165:     /*
166:       Set the type if it was never set.
167:     */
168:     if (!st->type_name) {
169:       STSetType(st,STSHIFT);
170:     }

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

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

177:     PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
178:     if (flg) { st->str = (MatStructure)i; }
179: 
180:     if (st->ops->setfromoptions) {
181:       (*st->ops->setfromoptions)(st);
182:     }

184:   PetscOptionsEnd();

186:   if (st->ksp) {
187:     if (st->shift_matrix == STMATMODE_SHELL) {
188:       /* if shift_mat is set then the default preconditioner is ILU,
189:          otherwise set Jacobi as the default */
190:       KSPGetPC(st->ksp,&pc);
191:       PCSetType(pc,PCJACOBI);
192:     }
193:     KSPSetFromOptions(st->ksp);
194:   }

196:   return(0);
197: }

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

207:    Collective on ST

209:    Input Parameters:
210: +  st  - the spectral transformation context
211: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
212:          SUBSET_NONZERO_PATTERN

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

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

227: .seealso: STSetOperators(), MatAXPY()
228: @*/
229: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
230: {
233:   st->str = str;
234:   return(0);
235: }

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

243:    Collective on ST

245:    Input Parameters:
246: +  st - the spectral transformation context
247: -  mode - the mode flag, one of STMATMODE_COPY, 
248:           STMATMODE_INPLACE or STMATMODE_SHELL

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

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

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

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

274:    Level: intermediate

276: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode()
277: @*/
278: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
279: {
282:   st->shift_matrix = mode;
283:   return(0);
284: }

288: /*@
289:    STGetMatMode - Gets a flag that indicates how the matrix is being 
290:    shifted in the shift-and-invert and Cayley spectral transformations.

292:    Collective on ST

294:    Input Parameter:
295: .  st - the spectral transformation context

297:    Output Parameter:
298: .  mode - the mode flag

300:    Level: intermediate

302: .seealso: STSetMatMode()
303: @*/
304: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
305: {
308:   *mode = st->shift_matrix;
309:   return(0);
310: }

314: /*@
315:    STSetBilinearForm - Specifies the bilinear form to be used for
316:    inner products in eigensolvers.

318:    Collective on ST

320:    Input Parameters:
321: +  st    - the spectral transformation context
322: -  form  - the type of bilinear form

324:    Note:
325:    This function is called by EPSSetProblemType() and usually need not be
326:    called by the user.

328:    Level: developer

330: .seealso: STInnerProduct(), STNorm(), EPSSetProblemType()
331: @*/
332: PetscErrorCode STSetBilinearForm(ST st,STBilinearForm form)
333: {
336:   st->bilinear_form = form;
337:   return(0);
338: }