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-2007, Universidad Politecnica de Valencia, Spain
8: This file is part of SLEPc. See the README file for conditions of use
9: and additional information.
10: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
11: */
13: #include src/st/stimpl.h
14: #include "petscsys.h"
16: /*
17: Contains the list of registered ST routines
18: */
19: PetscFList STList = 0;
23: /*@C
24: STSetType - Builds ST for a particular spectral transformation.
26: Collective on ST
28: Input Parameter:
29: + st - the spectral transformation context.
30: - type - a known type
32: Options Database Key:
33: . -st_type <type> - Sets ST type
35: Use -help for a list of available transformations
37: Notes:
38: See "slepc/include/slepcst.h" for available transformations
40: Normally, it is best to use the EPSSetFromOptions() command and
41: then set the ST type from the options database rather than by using
42: this routine. Using the options database provides the user with
43: maximum flexibility in evaluating the many different transformations.
45: Level: intermediate
47: .seealso: EPSSetType()
49: @*/
50: PetscErrorCode STSetType(ST st,STType type)
51: {
52: PetscErrorCode ierr,(*r)(ST);
53: PetscTruth match;
59: PetscTypeCompare((PetscObject)st,type,&match);
60: if (match) return(0);
62: if (st->ops->destroy) { (*st->ops->destroy)(st);}
63: PetscFListDestroy(&st->qlist);
64: st->data = 0;
65: st->setupcalled = 0;
67: /* Determine the STCreateXXX routine for a particular type */
68: PetscFListFind(STList, st->comm, type,(void (**)(void)) &r );
69: if (!r) SETERRQ1(1,"Unable to find requested ST type %s",type);
70: PetscFree(st->data);
72: PetscMemzero(st->ops,sizeof(struct _STOps));
74: /* Call the STCreateXXX routine for this particular type */
75: (*r)(st);
77: PetscObjectChangeTypeName((PetscObject)st,type);
78: return(0);
79: }
83: /*@C
84: STGetType - Gets the ST type name (as a string) from the ST context.
86: Not Collective
88: Input Parameter:
89: . st - the spectral transformation context
91: Output Parameter:
92: . name - name of the spectral transformation
94: Level: intermediate
96: .seealso: STSetType()
98: @*/
99: PetscErrorCode STGetType(ST st,STType *meth)
100: {
102: *meth = (STType) st->type_name;
103: return(0);
104: }
108: /*@
109: STSetFromOptions - Sets ST options from the options database.
110: This routine must be called before STSetUp() if the user is to be
111: allowed to set the type of transformation.
113: Collective on ST
115: Input Parameter:
116: . st - the spectral transformation context
118: Level: beginner
120: .seealso:
122: @*/
123: PetscErrorCode STSetFromOptions(ST st)
124: {
126: PetscInt i;
127: char type[256];
128: PetscTruth flg;
129: const char *mode_list[3] = { "copy", "inplace", "shell" };
130: const char *structure_list[3] = { "same", "different", "subset" };
131: PC pc;
136: PetscOptionsBegin(st->comm,st->prefix,"Spectral Transformation (ST) Options","ST");
137: PetscOptionsList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(st->type_name?st->type_name:STSHIFT),type,256,&flg);
138: if (flg) {
139: STSetType(st,type);
140: }
141: /*
142: Set the type if it was never set.
143: */
144: if (!st->type_name) {
145: STSetType(st,STSHIFT);
146: }
148: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&st->sigma,PETSC_NULL);
150: PetscOptionsEList("-st_matmode", "Shift matrix mode","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
151: if (flg) { st->shift_matrix = (STMatMode)i; }
153: PetscOptionsEList("-st_matstructure", "Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
154: if (flg) { st->str = (MatStructure)i; }
155:
156: if (st->ops->setfromoptions) {
157: (*st->ops->setfromoptions)(st);
158: }
160: PetscOptionsEnd();
162: if (st->ksp) {
163: if (st->shift_matrix == STMATMODE_SHELL) {
164: /* if shift_mat is set then the default preconditioner is ILU,
165: otherwise set Jacobi as the default */
166: KSPGetPC(st->ksp,&pc);
167: PCSetType(pc,PCJACOBI);
168: }
169: KSPSetFromOptions(st->ksp);
170: }
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. This function
181: has no effect in the case of standard eigenproblems.
183: Collective on ST
185: Input Parameters:
186: + st - the spectral transformation context
187: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
188: SUBSET_NONZERO_PATTERN
190: Options Database Key:
191: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
192: of 'same' (A and B have the same nonzero pattern), 'different' (A
193: and B have different nonzero pattern) or 'subset' (B's nonzero
194: pattern is a subset of A's).
196: Note:
197: By default, the sparsity patterns are assumed to be different. If the
198: patterns are equal or a subset then it is recommended to set this attribute
199: for efficiency reasons (in particular, for internal MatAXPY() operations).
200:
201: Level: advanced
203: .seealso: STSetOperators(), MatAXPY()
204: @*/
205: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
206: {
209: switch (str) {
210: case SAME_NONZERO_PATTERN:
211: case DIFFERENT_NONZERO_PATTERN:
212: case SUBSET_NONZERO_PATTERN:
213: st->str = str;
214: break;
215: default:
216: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
217: }
218: return(0);
219: }
223: /*@
224: STSetMatMode - Sets a flag to indicate how the matrix is
225: being shifted in the shift-and-invert and Cayley spectral transformations.
227: Collective on ST
229: Input Parameters:
230: + st - the spectral transformation context
231: - mode - the mode flag, one of STMATMODE_COPY,
232: STMATMODE_INPLACE or STMATMODE_SHELL
234: Options Database Key:
235: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
236: 'copy', 'inplace' or 'shell' (see explanation below).
238: Notes:
239: By default (STMATMODE_COPY), a copy of matrix A is made and then
240: this copy is shifted explicitly, e.g. A <- (A - s B).
242: With STMATMODE_INPLACE, the original matrix A is shifted at
243: STSetUp() and unshifted at the end of the computations. With respect to
244: the previous one, this mode avoids a copy of matrix A. However, a
245: backdraw is that the recovered matrix might be slightly different
246: from the original one (due to roundoff).
248: With STMATMODE_SHELL, the solver works with an implicit shell
249: matrix that represents the shifted matrix. This mode is the most efficient
250: in creating the shifted matrix but it places serious limitations to the
251: linear solves performed in each iteration of the eigensolver (typically,
252: only interative solvers with Jacobi preconditioning can be used).
253:
254: In the case of generalized problems, in the two first modes the matrix
255: A - s B has to be computed explicitly. The efficiency of this computation
256: can be controlled with STSetMatStructure().
258: Level: intermediate
260: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
261: @*/
262: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
263: {
266: st->shift_matrix = mode;
267: return(0);
268: }
272: /*@C
273: STGetMatMode - Gets a flag that indicates how the matrix is being
274: shifted in the shift-and-invert and Cayley spectral transformations.
276: Collective on ST
278: Input Parameter:
279: . st - the spectral transformation context
281: Output Parameter:
282: . mode - the mode flag
284: Level: intermediate
286: .seealso: STSetMatMode(), STMatMode
287: @*/
288: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
289: {
292: *mode = st->shift_matrix;
293: return(0);
294: }