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-2011, Universitat 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> /*I "slepcst.h" I*/
26: PetscBool STRegisterAllCalled = PETSC_FALSE;
27: PetscFList STList = 0;
31: /*@C
32: STSetType - Builds ST for a particular spectral transformation.
34: Logically Collective on ST
36: Input Parameter:
37: + st - the spectral transformation context.
38: - type - a known type
40: Options Database Key:
41: . -st_type <type> - Sets ST type
43: Use -help for a list of available transformations
45: Notes:
46: See "slepc/include/slepcst.h" for available transformations
48: Normally, it is best to use the EPSSetFromOptions() command and
49: then set the ST type from the options database rather than by using
50: this routine. Using the options database provides the user with
51: maximum flexibility in evaluating the many different transformations.
53: Level: intermediate
55: .seealso: EPSSetType()
57: @*/
58: PetscErrorCode STSetType(ST st,const STType type)
59: {
60: PetscErrorCode ierr,(*r)(ST);
61: PetscBool match;
67: PetscTypeCompare((PetscObject)st,type,&match);
68: if (match) return(0);
70: PetscFListFind(STList,((PetscObject)st)->comm,type,PETSC_TRUE,(void (**)(void))&r);
71: if (!r) SETERRQ1(((PetscObject)st)->comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
73: if (st->ops->destroy) { (*st->ops->destroy)(st); }
74: PetscMemzero(st->ops,sizeof(struct _STOps));
76: st->setupcalled = 0;
77: PetscObjectChangeTypeName((PetscObject)st,type);
78: (*r)(st);
79: return(0);
80: }
84: /*@C
85: STGetType - Gets the ST type name (as a string) from the ST context.
87: Not Collective
89: Input Parameter:
90: . st - the spectral transformation context
92: Output Parameter:
93: . name - name of the spectral transformation
95: Level: intermediate
97: .seealso: STSetType()
99: @*/
100: PetscErrorCode STGetType(ST st,const STType *type)
101: {
105: *type = ((PetscObject)st)->type_name;
106: return(0);
107: }
111: /*@
112: STSetFromOptions - Sets ST options from the options database.
113: This routine must be called before STSetUp() if the user is to be
114: allowed to set the type of transformation.
116: Collective on ST
118: Input Parameter:
119: . st - the spectral transformation context
121: Level: beginner
123: .seealso:
125: @*/
126: PetscErrorCode STSetFromOptions(ST st)
127: {
129: PetscInt i;
130: PetscScalar s;
131: char type[256];
132: PetscBool flg;
133: const char *mode_list[3] = {"copy","inplace","shell"};
134: const char *structure_list[3] = {"same","different","subset"};
138: if (!STRegisterAllCalled) { STRegisterAll(PETSC_NULL); }
139: PetscOptionsBegin(((PetscObject)st)->comm,((PetscObject)st)->prefix,"Spectral Transformation (ST) Options","ST");
140: PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
141: if (flg) {
142: STSetType(st,type);
143: }
144: /*
145: Set the type if it was never set.
146: */
147: if (!((PetscObject)st)->type_name) {
148: STSetType(st,STSHIFT);
149: }
151: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
152: if (flg) { STSetShift(st,s); }
154: PetscOptionsEList("-st_matmode","Shift matrix mode","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
155: if (flg) { st->shift_matrix = (STMatMode)i; }
157: PetscOptionsEList("-st_matstructure","Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
158: if (flg) {
159: switch (i) {
160: case 0: STSetMatStructure(st,SAME_NONZERO_PATTERN); break;
161: case 1: STSetMatStructure(st,DIFFERENT_NONZERO_PATTERN); break;
162: case 2: STSetMatStructure(st,SUBSET_NONZERO_PATTERN); break;
163: }
164: }
165:
166: if (st->ops->setfromoptions) {
167: (*st->ops->setfromoptions)(st);
168: }
169: PetscObjectProcessOptionsHandlers((PetscObject)st);
170: PetscOptionsEnd();
171: KSPSetFromOptions(st->ksp);
172: return(0);
173: }
177: /*@
178: STSetMatStructure - Sets an internal MatStructure attribute to
179: indicate which is the relation of the sparsity pattern of the two matrices
180: A and B constituting the generalized eigenvalue problem.
182: Logically Collective on ST
184: Input Parameters:
185: + st - the spectral transformation context
186: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
187: SUBSET_NONZERO_PATTERN
189: Options Database Key:
190: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
191: of 'same' (A and B have the same nonzero pattern), 'different' (A
192: and B have different nonzero pattern) or 'subset' (B's nonzero
193: pattern is a subset of A's).
195: Notes:
196: By default, the sparsity patterns are assumed to be different. If the
197: patterns are equal or a subset then it is recommended to set this attribute
198: for efficiency reasons (in particular, for internal MatAXPY() operations).
200: This function has no effect in the case of standard eigenproblems.
201:
202: Level: advanced
204: .seealso: STSetOperators(), MatAXPY()
205: @*/
206: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
207: {
211: switch (str) {
212: case SAME_NONZERO_PATTERN:
213: case DIFFERENT_NONZERO_PATTERN:
214: case SUBSET_NONZERO_PATTERN:
215: st->str = str;
216: break;
217: default:
218: SETERRQ(((PetscObject)st)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
219: }
220: return(0);
221: }
225: /*@
226: STGetMatStructure - Gets the internal MatStructure attribute to
227: indicate which is the relation of the sparsity pattern of the two matrices
228: A and B constituting the generalized eigenvalue problem.
230: Not Collective
232: Input Parameters:
233: . st - the spectral transformation context
235: Output Parameters:
236: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
237: SUBSET_NONZERO_PATTERN
239: Note:
240: This function has no effect in the case of standard eigenproblems.
242: Level: advanced
244: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
245: @*/
246: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
247: {
251: *str = st->str;
252: return(0);
253: }
257: /*@
258: STSetMatMode - Sets a flag to indicate how the matrix is
259: being shifted in the shift-and-invert and Cayley spectral transformations.
261: Logically Collective on ST
263: Input Parameters:
264: + st - the spectral transformation context
265: - mode - the mode flag, one of ST_MATMODE_COPY,
266: ST_MATMODE_INPLACE or ST_MATMODE_SHELL
268: Options Database Key:
269: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
270: 'copy', 'inplace' or 'shell' (see explanation below).
272: Notes:
273: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
274: this copy is shifted explicitly, e.g. A <- (A - s B).
276: With ST_MATMODE_INPLACE, the original matrix A is shifted at
277: STSetUp() and unshifted at the end of the computations. With respect to
278: the previous one, this mode avoids a copy of matrix A. However, a
279: backdraw is that the recovered matrix might be slightly different
280: from the original one (due to roundoff).
282: With ST_MATMODE_SHELL, the solver works with an implicit shell
283: matrix that represents the shifted matrix. This mode is the most efficient
284: in creating the shifted matrix but it places serious limitations to the
285: linear solves performed in each iteration of the eigensolver (typically,
286: only interative solvers with Jacobi preconditioning can be used).
287:
288: In the case of generalized problems, in the two first modes the matrix
289: A - s B has to be computed explicitly. The efficiency of this computation
290: can be controlled with STSetMatStructure().
292: Level: intermediate
294: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
295: @*/
296: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
297: {
301: st->shift_matrix = mode;
302: return(0);
303: }
307: /*@C
308: STGetMatMode - Gets a flag that indicates how the matrix is being
309: shifted in the shift-and-invert and Cayley spectral transformations.
311: Not Collective
313: Input Parameter:
314: . st - the spectral transformation context
316: Output Parameter:
317: . mode - the mode flag
319: Level: intermediate
321: .seealso: STSetMatMode(), STMatMode
322: @*/
323: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
324: {
328: *mode = st->shift_matrix;
329: return(0);
330: }