1: /*
2: Routines to set ST methods and options.
4: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5: SLEPc - Scalable Library for Eigenvalue Problem Computations
6: Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain
8: This file is part of SLEPc.
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 <slepc/private/stimpl.h> /*I "slepcst.h" I*/
26: PetscBool STRegisterAllCalled = PETSC_FALSE;
27: PetscFunctionList 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: beginner
55: .seealso: EPSSetType()
57: @*/
58: PetscErrorCode STSetType(ST st,STType type) 59: {
60: PetscErrorCode ierr,(*r)(ST);
61: PetscBool match;
67: PetscObjectTypeCompare((PetscObject)st,type,&match);
68: if (match) return(0);
70: PetscFunctionListFind(STList,type,&r);
71: if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),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,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 ST118: Input Parameter:
119: . st - the spectral transformation context
121: Level: beginner
122: @*/
123: PetscErrorCode STSetFromOptions(ST st)124: {
126: PetscInt i;
127: PetscScalar s;
128: char type[256];
129: PetscBool flg;
130: const char *mode_list[3] = {"copy","inplace","shell"};
131: const char *structure_list[3] = {"same","different","subset"};
135: STRegisterAll();
136: PetscObjectOptionsBegin((PetscObject)st);
137: PetscOptionsFList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)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 (!((PetscObject)st)->type_name) {
145: STSetType(st,STSHIFT);
146: }
148: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
149: if (flg) {
150: STSetShift(st,s);
151: }
153: PetscOptionsEList("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
154: if (flg) st->shift_matrix = (STMatMode)i;
156: PetscOptionsEList("-st_matstructure","Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
157: if (flg) {
158: switch (i) {
159: case 0: STSetMatStructure(st,SAME_NONZERO_PATTERN); break;
160: case 1: STSetMatStructure(st,DIFFERENT_NONZERO_PATTERN); break;
161: case 2: STSetMatStructure(st,SUBSET_NONZERO_PATTERN); break;
162: }
163: }
165: PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&st->transform,&flg);
167: if (st->ops->setfromoptions) {
168: (*st->ops->setfromoptions)(PetscOptionsObject,st);
169: }
170: PetscObjectProcessOptionsHandlers((PetscObject)st);
171: PetscOptionsEnd();
172: if (!st->ksp) { STGetKSP(st,&st->ksp); }
173: KSPSetFromOptions(st->ksp);
174: return(0);
175: }
179: /*@
180: STSetMatStructure - Sets an internal MatStructure attribute to
181: indicate which is the relation of the sparsity pattern of all ST matrices.
183: Logically Collective on ST185: 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' (matrices have the same nonzero pattern), 'different'
193: (different nonzero pattern) or 'subset' (pattern is a subset of the
194: first one).
196: Notes:
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).
201: This function has no effect in the case of standard eigenproblems.
203: Level: advanced
205: .seealso: STSetOperators(), MatAXPY()
206: @*/
207: PetscErrorCode STSetMatStructure(ST st,MatStructure str)208: {
212: switch (str) {
213: case SAME_NONZERO_PATTERN:
214: case DIFFERENT_NONZERO_PATTERN:
215: case SUBSET_NONZERO_PATTERN:
216: st->str = str;
217: break;
218: default:219: SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
220: }
221: return(0);
222: }
226: /*@
227: STGetMatStructure - Gets the internal MatStructure attribute to
228: indicate which is the relation of the sparsity pattern of the matrices.
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: Level: advanced
241: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
242: @*/
243: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)244: {
248: *str = st->str;
249: return(0);
250: }
254: /*@
255: STSetMatMode - Sets a flag to indicate how the transformed matrices are
256: being stored in the spectral transformations.
258: Logically Collective on ST260: Input Parameters:
261: + st - the spectral transformation context
262: - mode - the mode flag, one of ST_MATMODE_COPY,
263: ST_MATMODE_INPLACE, or ST_MATMODE_SHELL
265: Options Database Key:
266: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
267: 'copy', 'inplace', 'shell' (see explanation below).
269: Notes:
270: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
271: this copy is modified explicitly, e.g. A <- (A - s B).
273: With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
274: and changes are reverted at the end of the computations. With respect to
275: the previous one, this mode avoids a copy of matrix A. However, a
276: drawback is that the recovered matrix might be slightly different
277: from the original one (due to roundoff).
279: With ST_MATMODE_SHELL, the solver works with an implicit shell
280: matrix that represents the shifted matrix. This mode is the most efficient
281: in creating the shifted matrix but it places serious limitations to the
282: linear solves performed in each iteration of the eigensolver (typically,
283: only interative solvers with Jacobi preconditioning can be used).
285: In the two first modes the efficiency of the computation
286: can be controlled with STSetMatStructure().
288: Level: intermediate
290: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode291: @*/
292: PetscErrorCode STSetMatMode(ST st,STMatMode mode)293: {
297: st->shift_matrix = mode;
298: st->setupcalled = 0;
299: return(0);
300: }
304: /*@
305: STGetMatMode - Gets a flag that indicates how the transformed matrices
306: are stored in spectral transformations.
308: Not Collective
310: Input Parameter:
311: . st - the spectral transformation context
313: Output Parameter:
314: . mode - the mode flag
316: Level: intermediate
318: .seealso: STSetMatMode(), STMatMode319: @*/
320: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)321: {
325: *mode = st->shift_matrix;
326: return(0);
327: }
331: /*@
332: STSetTransform - Sets a flag to indicate whether the transformed matrices are
333: computed or not.
335: Logically Collective on ST337: Input Parameters:
338: + st - the spectral transformation context
339: - flg - the boolean flag
341: Options Database Key:
342: . -st_transform <bool> - Activate/deactivate the computation of matrices.
344: Notes:
345: This flag is intended for the case of polynomial eigenproblems solved
346: via linearization. If this flag is off (default) the spectral transformation
347: is applied to the linearization (handled by the eigensolver), otherwise
348: it is applied to the original problem.
350: Level: developer
352: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
353: @*/
354: PetscErrorCode STSetTransform(ST st,PetscBool flg)355: {
359: st->transform = flg;
360: st->setupcalled = 0;
361: return(0);
362: }
366: /*@
367: STGetTransform - Gets a flag that that indicates whether the transformed
368: matrices are computed or not.
370: Not Collective
372: Input Parameter:
373: . st - the spectral transformation context
375: Output Parameter:
376: . flg - the flag
378: Level: developer
380: .seealso: STSetTransform()
381: @*/
382: PetscErrorCode STGetTransform(ST st,PetscBool *flg)383: {
387: *flg = st->transform;
388: return(0);
389: }