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