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: }