1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2019, Universitat Politecnica de Valencia, Spain
6: This file is part of SLEPc.
7: SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9: */
10: /*
11: Routines to set ST methods and options
12: */
14: #include <slepc/private/stimpl.h> /*I "slepcst.h" I*/
16: PetscBool STRegisterAllCalled = PETSC_FALSE;
17: PetscFunctionList STList = 0;
19: /*@C
20: STSetType - Builds ST for a particular spectral transformation.
22: Logically Collective on ST 24: Input Parameter:
25: + st - the spectral transformation context.
26: - type - a known type
28: Options Database Key:
29: . -st_type <type> - Sets ST type
31: Use -help for a list of available transformations
33: Notes:
34: See "slepc/include/slepcst.h" for available transformations
36: Normally, it is best to use the EPSSetFromOptions() command and
37: then set the ST type from the options database rather than by using
38: this routine. Using the options database provides the user with
39: maximum flexibility in evaluating the many different transformations.
41: Level: beginner
43: .seealso: EPSSetType()
45: @*/
46: PetscErrorCode STSetType(ST st,STType type) 47: {
48: PetscErrorCode ierr,(*r)(ST);
49: PetscBool match;
55: PetscObjectTypeCompare((PetscObject)st,type,&match);
56: if (match) return(0);
58: PetscFunctionListFind(STList,type,&r);
59: if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
61: if (st->ops->destroy) { (*st->ops->destroy)(st); }
62: PetscMemzero(st->ops,sizeof(struct _STOps));
64: st->state = ST_STATE_INITIAL;
65: PetscObjectChangeTypeName((PetscObject)st,type);
66: (*r)(st);
67: return(0);
68: }
70: /*@C
71: STGetType - Gets the ST type name (as a string) from the ST context.
73: Not Collective
75: Input Parameter:
76: . st - the spectral transformation context
78: Output Parameter:
79: . name - name of the spectral transformation
81: Level: intermediate
83: .seealso: STSetType()
85: @*/
86: PetscErrorCode STGetType(ST st,STType *type) 87: {
91: *type = ((PetscObject)st)->type_name;
92: return(0);
93: }
95: /*@
96: STSetFromOptions - Sets ST options from the options database.
97: This routine must be called before STSetUp() if the user is to be
98: allowed to set the type of transformation.
100: Collective on ST102: Input Parameter:
103: . st - the spectral transformation context
105: Level: beginner
106: @*/
107: PetscErrorCode STSetFromOptions(ST st)108: {
110: PetscScalar s;
111: char type[256];
112: PetscBool flg;
113: const char *structure_list[3] = {"same","different","subset"};
114: STMatMode mode;
115: MatStructure mstr;
119: STRegisterAll();
120: PetscObjectOptionsBegin((PetscObject)st);
121: PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
122: if (flg) {
123: STSetType(st,type);
124: } else if (!((PetscObject)st)->type_name) {
125: STSetType(st,STSHIFT);
126: }
128: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
129: if (flg) { STSetShift(st,s); }
131: PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->shift_matrix,(PetscEnum*)&mode,&flg);
132: if (flg) { STSetMatMode(st,mode); }
134: PetscOptionsEList("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",structure_list,3,structure_list[st->str],(PetscInt*)&mstr,&flg);
135: if (flg) { STSetMatStructure(st,mstr); }
137: PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&st->transform,&flg);
139: if (st->ops->setfromoptions) {
140: (*st->ops->setfromoptions)(PetscOptionsObject,st);
141: }
142: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
143: PetscOptionsEnd();
145: STSetDefaultKSP(st);
146: KSPSetFromOptions(st->ksp);
147: return(0);
148: }
150: /*@
151: STSetMatStructure - Sets an internal MatStructure attribute to
152: indicate which is the relation of the sparsity pattern of all ST matrices.
154: Logically Collective on ST156: Input Parameters:
157: + st - the spectral transformation context
158: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
159: SUBSET_NONZERO_PATTERN
161: Options Database Key:
162: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
163: of 'same' (matrices have the same nonzero pattern), 'different'
164: (different nonzero pattern) or 'subset' (pattern is a subset of the
165: first one).
167: Notes:
168: By default, the sparsity patterns are assumed to be different. If the
169: patterns are equal or a subset then it is recommended to set this attribute
170: for efficiency reasons (in particular, for internal MatAXPY() operations).
172: This function has no effect in the case of standard eigenproblems.
174: Level: advanced
176: .seealso: STSetMatrices(), MatAXPY()
177: @*/
178: PetscErrorCode STSetMatStructure(ST st,MatStructure str)179: {
183: switch (str) {
184: case SAME_NONZERO_PATTERN:
185: case DIFFERENT_NONZERO_PATTERN:
186: case SUBSET_NONZERO_PATTERN:
187: st->str = str;
188: break;
189: default:190: SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
191: }
192: return(0);
193: }
195: /*@
196: STGetMatStructure - Gets the internal MatStructure attribute to
197: indicate which is the relation of the sparsity pattern of the matrices.
199: Not Collective
201: Input Parameters:
202: . st - the spectral transformation context
204: Output Parameters:
205: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
206: SUBSET_NONZERO_PATTERN
208: Level: advanced
210: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
211: @*/
212: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)213: {
217: *str = st->str;
218: return(0);
219: }
221: /*@
222: STSetMatMode - Sets a flag to indicate how the transformed matrices are
223: being stored in the spectral transformations.
225: Logically Collective on ST227: Input Parameters:
228: + st - the spectral transformation context
229: - mode - the mode flag, one of ST_MATMODE_COPY,
230: ST_MATMODE_INPLACE, or ST_MATMODE_SHELL232: Options Database Key:
233: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
234: 'copy', 'inplace', 'shell' (see explanation below).
236: Notes:
237: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
238: this copy is modified explicitly, e.g. A <- (A - s B).
240: With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
241: and changes are reverted at the end of the computations. With respect to
242: the previous one, this mode avoids a copy of matrix A. However, a
243: drawback is that the recovered matrix might be slightly different
244: from the original one (due to roundoff).
246: With ST_MATMODE_SHELL, the solver works with an implicit shell
247: matrix that represents the shifted matrix. This mode is the most efficient
248: in creating the shifted matrix but it places serious limitations to the
249: linear solves performed in each iteration of the eigensolver (typically,
250: only interative solvers with Jacobi preconditioning can be used).
252: In the two first modes the efficiency of the computation
253: can be controlled with STSetMatStructure().
255: Level: intermediate
257: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode258: @*/
259: PetscErrorCode STSetMatMode(ST st,STMatMode mode)260: {
264: if (st->shift_matrix != mode) {
265: st->shift_matrix = mode;
266: st->state = ST_STATE_INITIAL;
267: }
268: return(0);
269: }
271: /*@
272: STGetMatMode - Gets a flag that indicates how the transformed matrices
273: are stored in spectral transformations.
275: Not Collective
277: Input Parameter:
278: . st - the spectral transformation context
280: Output Parameter:
281: . mode - the mode flag
283: Level: intermediate
285: .seealso: STSetMatMode(), STMatMode286: @*/
287: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)288: {
292: *mode = st->shift_matrix;
293: return(0);
294: }
296: /*@
297: STSetTransform - Sets a flag to indicate whether the transformed matrices are
298: computed or not.
300: Logically Collective on ST302: Input Parameters:
303: + st - the spectral transformation context
304: - flg - the boolean flag
306: Options Database Key:
307: . -st_transform <bool> - Activate/deactivate the computation of matrices.
309: Notes:
310: This flag is intended for the case of polynomial eigenproblems solved
311: via linearization. If this flag is off (default) the spectral transformation
312: is applied to the linearization (handled by the eigensolver), otherwise
313: it is applied to the original problem.
315: Level: developer
317: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
318: @*/
319: PetscErrorCode STSetTransform(ST st,PetscBool flg)320: {
324: if (st->transform != flg) {
325: st->transform = flg;
326: st->state = ST_STATE_INITIAL;
327: }
328: return(0);
329: }
331: /*@
332: STGetTransform - Gets a flag that that indicates whether the transformed
333: matrices are computed or not.
335: Not Collective
337: Input Parameter:
338: . st - the spectral transformation context
340: Output Parameter:
341: . flg - the flag
343: Level: developer
345: .seealso: STSetTransform()
346: @*/
347: PetscErrorCode STGetTransform(ST st,PetscBool *flg)348: {
352: *flg = st->transform;
353: return(0);
354: }