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-2010, 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: PetscScalar s;
141: char type[256];
142: PetscTruth flg;
143: const char *mode_list[3] = { "copy", "inplace", "shell" };
144: const char *structure_list[3] = { "same", "different", "subset" };
149: PetscOptionsBegin(((PetscObject)st)->comm,((PetscObject)st)->prefix,"Spectral Transformation (ST) Options","ST");
150: PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
151: if (flg) {
152: STSetType(st,type);
153: }
154: /*
155: Set the type if it was never set.
156: */
157: if (!((PetscObject)st)->type_name) {
158: STSetType(st,STSHIFT);
159: }
161: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
162: if (flg) { STSetShift(st,s); }
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: KSPSetFromOptions(st->ksp);
178: return(0);
179: }
183: /*@
184: STSetMatStructure - Sets an internal MatStructure attribute to
185: indicate which is the relation of the sparsity pattern of the two matrices
186: A and B constituting the generalized eigenvalue problem. This function
187: has no effect in the case of standard eigenproblems.
189: Collective on ST
191: Input Parameters:
192: + st - the spectral transformation context
193: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
194: SUBSET_NONZERO_PATTERN
196: Options Database Key:
197: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
198: of 'same' (A and B have the same nonzero pattern), 'different' (A
199: and B have different nonzero pattern) or 'subset' (B's nonzero
200: pattern is a subset of A's).
202: Note:
203: By default, the sparsity patterns are assumed to be different. If the
204: patterns are equal or a subset then it is recommended to set this attribute
205: for efficiency reasons (in particular, for internal MatAXPY() operations).
206:
207: Level: advanced
209: .seealso: STSetOperators(), MatAXPY()
210: @*/
211: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
212: {
215: switch (str) {
216: case SAME_NONZERO_PATTERN:
217: case DIFFERENT_NONZERO_PATTERN:
218: case SUBSET_NONZERO_PATTERN:
219: st->str = str;
220: break;
221: default:
222: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
223: }
224: return(0);
225: }
229: /*@
230: STGetMatStructure - Gets the internal MatStructure attribute to
231: indicate which is the relation of the sparsity pattern of the two matrices
232: A and B constituting the generalized eigenvalue problem. This function
233: has no effect in the case of standard eigenproblems.
235: Collective on ST
237: Input Parameters:
238: . st - the spectral transformation context
240: Output Parameters:
241: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
242: SUBSET_NONZERO_PATTERN
244: Level: advanced
246: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
247: @*/
248: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
249: {
253: *str = st->str;
254: return(0);
255: }
259: /*@
260: STSetMatMode - Sets a flag to indicate how the matrix is
261: being shifted in the shift-and-invert and Cayley spectral transformations.
263: Collective on ST
265: Input Parameters:
266: + st - the spectral transformation context
267: - mode - the mode flag, one of ST_MATMODE_COPY,
268: ST_MATMODE_INPLACE or ST_MATMODE_SHELL
270: Options Database Key:
271: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
272: 'copy', 'inplace' or 'shell' (see explanation below).
274: Notes:
275: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
276: this copy is shifted explicitly, e.g. A <- (A - s B).
278: With ST_MATMODE_INPLACE, the original matrix A is shifted at
279: STSetUp() and unshifted at the end of the computations. With respect to
280: the previous one, this mode avoids a copy of matrix A. However, a
281: backdraw is that the recovered matrix might be slightly different
282: from the original one (due to roundoff).
284: With ST_MATMODE_SHELL, the solver works with an implicit shell
285: matrix that represents the shifted matrix. This mode is the most efficient
286: in creating the shifted matrix but it places serious limitations to the
287: linear solves performed in each iteration of the eigensolver (typically,
288: only interative solvers with Jacobi preconditioning can be used).
289:
290: In the case of generalized problems, in the two first modes the matrix
291: A - s B has to be computed explicitly. The efficiency of this computation
292: can be controlled with STSetMatStructure().
294: Level: intermediate
296: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
297: @*/
298: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
299: {
302: st->shift_matrix = mode;
303: return(0);
304: }
308: /*@C
309: STGetMatMode - Gets a flag that indicates how the matrix is being
310: shifted in the shift-and-invert and Cayley spectral transformations.
312: Collective on ST
314: Input Parameter:
315: . st - the spectral transformation context
317: Output Parameter:
318: . mode - the mode flag
320: Level: intermediate
322: .seealso: STSetMatMode(), STMatMode
323: @*/
324: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
325: {
328: *mode = st->shift_matrix;
329: return(0);
330: }