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-2009, Universidad Politecnica de Valencia, Spain
8: This file is part of SLEPc.
9:
10: SLEPc is free software: you can redistribute it and/or modify it under the
11: terms of version 3 of the GNU Lesser General Public License as published by
12: the Free Software Foundation.
14: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
15: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
17: more details.
19: You should have received a copy of the GNU Lesser General Public License
20: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
21: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
22: */
24: #include private/stimpl.h
25: #include "petscsys.h"
27: /*
28: Contains the list of registered ST routines
29: */
30: PetscFList STList = 0;
34: /*@C
35: STSetType - Builds ST for a particular spectral transformation.
37: Collective on ST
39: Input Parameter:
40: + st - the spectral transformation context.
41: - type - a known type
43: Options Database Key:
44: . -st_type <type> - Sets ST type
46: Use -help for a list of available transformations
48: Notes:
49: See "slepc/include/slepcst.h" for available transformations
51: Normally, it is best to use the EPSSetFromOptions() command and
52: then set the ST type from the options database rather than by using
53: this routine. Using the options database provides the user with
54: maximum flexibility in evaluating the many different transformations.
56: Level: intermediate
58: .seealso: EPSSetType()
60: @*/
61: PetscErrorCode STSetType(ST st,const STType type)
62: {
63: PetscErrorCode ierr,(*r)(ST);
64: PetscTruth match;
70: PetscTypeCompare((PetscObject)st,type,&match);
71: if (match) return(0);
73: if (st->ops->destroy) { (*st->ops->destroy)(st);}
74: PetscFListDestroy(&((PetscObject)st)->qlist);
75: st->data = 0;
76: st->setupcalled = 0;
78: /* Determine the STCreateXXX routine for a particular type */
79: PetscFListFind(STList, ((PetscObject)st)->comm, type,(void (**)(void)) &r );
80: if (!r) SETERRQ1(1,"Unable to find requested ST type %s",type);
81: PetscFree(st->data);
83: PetscMemzero(st->ops,sizeof(struct _STOps));
85: /* Call the STCreateXXX routine for this particular type */
86: (*r)(st);
88: PetscObjectChangeTypeName((PetscObject)st,type);
89: return(0);
90: }
94: /*@C
95: STGetType - Gets the ST type name (as a string) from the ST context.
97: Not Collective
99: Input Parameter:
100: . st - the spectral transformation context
102: Output Parameter:
103: . name - name of the spectral transformation
105: Level: intermediate
107: .seealso: STSetType()
109: @*/
110: PetscErrorCode STGetType(ST st,const STType *type)
111: {
115: *type = ((PetscObject)st)->type_name;
116: return(0);
117: }
121: /*@
122: STSetFromOptions - Sets ST options from the options database.
123: This routine must be called before STSetUp() if the user is to be
124: allowed to set the type of transformation.
126: Collective on ST
128: Input Parameter:
129: . st - the spectral transformation context
131: Level: beginner
133: .seealso:
135: @*/
136: PetscErrorCode STSetFromOptions(ST st)
137: {
139: PetscInt i;
140: char type[256];
141: PetscTruth flg;
142: const char *mode_list[3] = { "copy", "inplace", "shell" };
143: const char *structure_list[3] = { "same", "different", "subset" };
144: PC pc;
145: const char *pctype;
150: PetscOptionsBegin(((PetscObject)st)->comm,((PetscObject)st)->prefix,"Spectral Transformation (ST) Options","ST");
151: PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
152: if (flg) {
153: STSetType(st,type);
154: }
155: /*
156: Set the type if it was never set.
157: */
158: if (!((PetscObject)st)->type_name) {
159: STSetType(st,STSHIFT);
160: }
162: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&st->sigma,PETSC_NULL);
164: PetscOptionsEList("-st_matmode", "Shift matrix mode","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
165: if (flg) { st->shift_matrix = (STMatMode)i; }
167: PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
168: if (flg) { st->str = (MatStructure)i; }
169:
170: if (st->ops->setfromoptions) {
171: (*st->ops->setfromoptions)(st);
172: }
174: PetscOptionsEnd();
176: if (st->ksp) {
177: KSPGetPC(st->ksp,&pc);
178: PCGetType(pc,&pctype);
179: if (!pctype) {
180: if (st->shift_matrix == STMATMODE_SHELL) {
181: /* in shell mode use GMRES with Jacobi as the default */
182: KSPSetType(st->ksp,KSPGMRES);
183: PCSetType(pc,PCJACOBI);
184: } else {
185: /* use direct solver as default */
186: KSPSetType(st->ksp,KSPPREONLY);
187: PCSetType(pc,PCREDUNDANT);
188: }
189: }
190: KSPSetFromOptions(st->ksp);
191: }
193: return(0);
194: }
198: /*@
199: STSetMatStructure - Sets an internal MatStructure attribute to
200: indicate which is the relation of the sparsity pattern of the two matrices
201: A and B constituting the generalized eigenvalue problem. This function
202: has no effect in the case of standard eigenproblems.
204: Collective on ST
206: Input Parameters:
207: + st - the spectral transformation context
208: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
209: SUBSET_NONZERO_PATTERN
211: Options Database Key:
212: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
213: of 'same' (A and B have the same nonzero pattern), 'different' (A
214: and B have different nonzero pattern) or 'subset' (B's nonzero
215: pattern is a subset of A's).
217: Note:
218: By default, the sparsity patterns are assumed to be different. If the
219: patterns are equal or a subset then it is recommended to set this attribute
220: for efficiency reasons (in particular, for internal MatAXPY() operations).
221:
222: Level: advanced
224: .seealso: STSetOperators(), MatAXPY()
225: @*/
226: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
227: {
230: switch (str) {
231: case SAME_NONZERO_PATTERN:
232: case DIFFERENT_NONZERO_PATTERN:
233: case SUBSET_NONZERO_PATTERN:
234: st->str = str;
235: break;
236: default:
237: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
238: }
239: return(0);
240: }
244: /*@
245: STSetMatMode - Sets a flag to indicate how the matrix is
246: being shifted in the shift-and-invert and Cayley spectral transformations.
248: Collective on ST
250: Input Parameters:
251: + st - the spectral transformation context
252: - mode - the mode flag, one of STMATMODE_COPY,
253: STMATMODE_INPLACE or STMATMODE_SHELL
255: Options Database Key:
256: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
257: 'copy', 'inplace' or 'shell' (see explanation below).
259: Notes:
260: By default (STMATMODE_COPY), a copy of matrix A is made and then
261: this copy is shifted explicitly, e.g. A <- (A - s B).
263: With STMATMODE_INPLACE, the original matrix A is shifted at
264: STSetUp() and unshifted at the end of the computations. With respect to
265: the previous one, this mode avoids a copy of matrix A. However, a
266: backdraw is that the recovered matrix might be slightly different
267: from the original one (due to roundoff).
269: With STMATMODE_SHELL, the solver works with an implicit shell
270: matrix that represents the shifted matrix. This mode is the most efficient
271: in creating the shifted matrix but it places serious limitations to the
272: linear solves performed in each iteration of the eigensolver (typically,
273: only interative solvers with Jacobi preconditioning can be used).
274:
275: In the case of generalized problems, in the two first modes the matrix
276: A - s B has to be computed explicitly. The efficiency of this computation
277: can be controlled with STSetMatStructure().
279: Level: intermediate
281: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
282: @*/
283: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
284: {
287: st->shift_matrix = mode;
288: return(0);
289: }
293: /*@C
294: STGetMatMode - Gets a flag that indicates how the matrix is being
295: shifted in the shift-and-invert and Cayley spectral transformations.
297: Collective on ST
299: Input Parameter:
300: . st - the spectral transformation context
302: Output Parameter:
303: . mode - the mode flag
305: Level: intermediate
307: .seealso: STSetMatMode(), STMatMode
308: @*/
309: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
310: {
313: *mode = st->shift_matrix;
314: return(0);
315: }