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: /*
 10:    Contains the list of registered EPS routines
 11: */
 12: PetscFList STList = 0;

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

 19:    Collective on ST

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

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

 28:    Use -help for a list of available transformations

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

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

 38:    Level: intermediate

 40: .seealso: EPSSetType()

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


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

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

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

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

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

 70:   PetscObjectChangeTypeName((PetscObject)st,type);
 71:   return(0);
 72: }

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

 79:    Not Collective

 81:    Input Parameter:
 82: .  st - the spectral transformation context

 84:    Output Parameter:
 85: .  name - name of the spectral transformation 

 87:    Level: intermediate

 89: .seealso: STSetType()

 91: @*/
 92: PetscErrorCode STGetType(ST st,STType *meth)
 93: {
 95:   *meth = (STType) st->type_name;
 96:   return(0);
 97: }

101: /*@
102:    STSetFromOptions - Sets ST options from the options database.
103:    This routine must be called before STSetUp() if the user is to be
104:    allowed to set the type of transformation.

106:    Collective on ST

108:    Input Parameter:
109: .  st - the spectral transformation context

111:    Level: beginner

113: .seealso: 

115: @*/
116: PetscErrorCode STSetFromOptions(ST st)
117: {
119:   PetscInt       i;
120:   char           type[256];
121:   PetscTruth     flg;
122:   const char     *mode_list[3] = { "copy", "inplace", "shell" };
123:   const char     *structure_list[3] = { "same", "different", "subset" };
124:   PC             pc;


129:   PetscOptionsBegin(st->comm,st->prefix,"Spectral Transformation (ST) Options","ST");
130:     PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(st->type_name?st->type_name:STSHIFT),type,256,&flg);
131:     if (flg) {
132:       STSetType(st,type);
133:     }
134:     /*
135:       Set the type if it was never set.
136:     */
137:     if (!st->type_name) {
138:       STSetType(st,STSHIFT);
139:     }

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

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

146:     PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
147:     if (flg) { st->str = (MatStructure)i; }
148: 
149:     if (st->ops->setfromoptions) {
150:       (*st->ops->setfromoptions)(st);
151:     }

153:   PetscOptionsEnd();

155:   if (st->ksp) {
156:     if (st->shift_matrix == STMATMODE_SHELL) {
157:       /* if shift_mat is set then the default preconditioner is ILU,
158:          otherwise set Jacobi as the default */
159:       KSPGetPC(st->ksp,&pc);
160:       PCSetType(pc,PCJACOBI);
161:     }
162:     KSPSetFromOptions(st->ksp);
163:   }

165:   return(0);
166: }

170: /*@
171:    STSetMatStructure - Sets an internal MatStructure attribute to 
172:    indicate which is the relation of the sparsity pattern of the two matrices
173:    A and B constituting the generalized eigenvalue problem. This function
174:    has no effect in the case of standard eigenproblems.

176:    Collective on ST

178:    Input Parameters:
179: +  st  - the spectral transformation context
180: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
181:          SUBSET_NONZERO_PATTERN

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

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

196: .seealso: STSetOperators(), MatAXPY()
197: @*/
198: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
199: {
202:   st->str = str;
203:   return(0);
204: }

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

212:    Collective on ST

214:    Input Parameters:
215: +  st - the spectral transformation context
216: -  mode - the mode flag, one of STMATMODE_COPY, 
217:           STMATMODE_INPLACE or STMATMODE_SHELL

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

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

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

233:    With STMATMODE_SHELL, the solver works with an implicit shell 
234:    matrix that represents the shifted matrix. This mode is the most efficient 
235:    in creating the shifted matrix but it places serious limitations to the 
236:    linear solves performed in each iteration of the eigensolver (typically,
237:    only interative solvers with Jacobi preconditioning can be used).
238:    
239:    In the case of generalized problems, in the two first modes the matrix
240:    A - s B has to be computed explicitly. The efficiency of this computation 
241:    can be controlled with STSetMatStructure().

243:    Level: intermediate

245: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode()
246: @*/
247: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
248: {
251:   st->shift_matrix = mode;
252:   return(0);
253: }

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

261:    Collective on ST

263:    Input Parameter:
264: .  st - the spectral transformation context

266:    Output Parameter:
267: .  mode - the mode flag

269:    Level: intermediate

271: .seealso: STSetMatMode()
272: @*/
273: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
274: {
277:   *mode = st->shift_matrix;
278:   return(0);
279: }

283: /*@
284:    STSetBilinearForm - Specifies the bilinear form to be used for
285:    inner products in eigensolvers.

287:    Collective on ST

289:    Input Parameters:
290: +  st    - the spectral transformation context
291: -  form  - the type of bilinear form

293:    Note:
294:    This function is called by EPSSetProblemType() and usually need not be
295:    called by the user.

297:    Level: developer

299: .seealso: STInnerProduct(), STNorm(), EPSSetProblemType()
300: @*/
301: PetscErrorCode STSetBilinearForm(ST st,STBilinearForm form)
302: {
305:   st->bilinear_form = form;
306:   return(0);
307: }