Actual source code: stset.c
slepc-3.18.0 2022-10-01
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-, 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>
16: PetscBool STRegisterAllCalled = PETSC_FALSE;
17: PetscFunctionList STList = NULL;
19: /*@C
20: STSetType - Builds ST for a particular spectral transformation.
22: Logically Collective on st
24: Input Parameters:
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 (*r)(ST);
49: PetscBool match;
54: PetscObjectTypeCompare((PetscObject)st,type,&match);
55: if (match) return 0;
56: STCheckNotSeized(st,1);
58: PetscFunctionListFind(STList,type,&r);
61: PetscTryTypeMethod(st,destroy);
62: PetscMemzero(st->ops,sizeof(struct _STOps));
64: st->state = ST_STATE_INITIAL;
65: st->opready = PETSC_FALSE;
66: PetscObjectChangeTypeName((PetscObject)st,type);
67: (*r)(st);
68: return 0;
69: }
71: /*@C
72: STGetType - Gets the ST type name (as a string) from the ST context.
74: Not Collective
76: Input Parameter:
77: . st - the spectral transformation context
79: Output Parameter:
80: . type - name of the spectral transformation
82: Level: intermediate
84: .seealso: STSetType()
86: @*/
87: PetscErrorCode STGetType(ST st,STType *type)
88: {
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 st
102: Input Parameter:
103: . st - the spectral transformation context
105: Level: beginner
107: .seealso: STSetOptionsPrefix()
108: @*/
109: PetscErrorCode STSetFromOptions(ST st)
110: {
111: PetscScalar s;
112: char type[256];
113: PetscBool flg,bval;
114: STMatMode mode;
115: MatStructure mstr;
118: STRegisterAll();
119: PetscObjectOptionsBegin((PetscObject)st);
120: PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg);
121: if (flg) STSetType(st,type);
122: else if (!((PetscObject)st)->type_name) STSetType(st,STSHIFT);
124: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
125: if (flg) STSetShift(st,s);
127: PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg);
128: if (flg) STSetMatMode(st,mode);
130: PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg);
131: if (flg) STSetMatStructure(st,mstr);
133: PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg);
134: if (flg) STSetTransform(st,bval);
136: PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
137: PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject);
138: PetscOptionsEnd();
140: if (st->usesksp) {
141: STSetDefaultKSP(st);
142: KSPSetFromOptions(st->ksp);
143: }
144: return 0;
145: }
147: /*@
148: STSetMatStructure - Sets an internal MatStructure attribute to
149: indicate which is the relation of the sparsity pattern of all ST matrices.
151: Logically Collective on st
153: Input Parameters:
154: + st - the spectral transformation context
155: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
156: SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
158: Options Database Key:
159: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
160: of 'same' (matrices have the same nonzero pattern), 'different'
161: (different nonzero pattern), 'subset' (pattern is a subset of the
162: first one), or 'unknown'.
164: Notes:
165: If the sparsity pattern of the second matrix is equal or a subset of the
166: pattern of the first matrix then it is recommended to set this attribute
167: for efficiency reasons (in particular, for internal MatAXPY() operations).
168: If not set, the default is UNKNOWN_NONZERO_PATTERN, in which case the patterns
169: will be compared to determine if they are equal.
171: This function has no effect in the case of standard eigenproblems.
173: In case of polynomial eigenproblems, the flag applies to all matrices
174: relative to the first one.
176: Level: advanced
178: .seealso: STSetMatrices(), MatAXPY()
179: @*/
180: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
181: {
184: switch (str) {
185: case SAME_NONZERO_PATTERN:
186: case DIFFERENT_NONZERO_PATTERN:
187: case SUBSET_NONZERO_PATTERN:
188: case UNKNOWN_NONZERO_PATTERN:
189: st->str = str;
190: break;
191: default:
192: SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
193: }
194: return 0;
195: }
197: /*@
198: STGetMatStructure - Gets the internal MatStructure attribute to
199: indicate which is the relation of the sparsity pattern of the matrices.
201: Not Collective
203: Input Parameters:
204: . st - the spectral transformation context
206: Output Parameters:
207: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
208: SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
210: Level: advanced
212: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
213: @*/
214: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
215: {
218: *str = st->str;
219: return 0;
220: }
222: /*@
223: STSetMatMode - Sets a flag to indicate how the transformed matrices are
224: being stored in the spectral transformations.
226: Logically Collective on st
228: Input Parameters:
229: + st - the spectral transformation context
230: - mode - the mode flag, one of ST_MATMODE_COPY,
231: ST_MATMODE_INPLACE, or ST_MATMODE_SHELL
233: Options Database Key:
234: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
235: 'copy', 'inplace', 'shell' (see explanation below).
237: Notes:
238: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
239: this copy is modified explicitly, e.g. A <- (A - s B).
241: With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
242: and changes are reverted at the end of the computations. With respect to
243: the previous one, this mode avoids a copy of matrix A. However, a
244: drawback is that the recovered matrix might be slightly different
245: from the original one (due to roundoff).
247: With ST_MATMODE_SHELL, the solver works with an implicit shell
248: matrix that represents the shifted matrix. This mode is the most efficient
249: in creating the shifted matrix but it places serious limitations to the
250: linear solves performed in each iteration of the eigensolver (typically,
251: only iterative solvers with Jacobi preconditioning can be used).
253: In the two first modes the efficiency of the computation
254: can be controlled with STSetMatStructure().
256: Level: intermediate
258: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
259: @*/
260: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
261: {
264: if (st->matmode != mode) {
265: STCheckNotSeized(st,1);
266: st->matmode = mode;
267: st->state = ST_STATE_INITIAL;
268: st->opready = PETSC_FALSE;
269: }
270: return 0;
271: }
273: /*@
274: STGetMatMode - Gets a flag that indicates how the transformed matrices
275: are stored in spectral transformations.
277: Not Collective
279: Input Parameter:
280: . st - the spectral transformation context
282: Output Parameter:
283: . mode - the mode flag
285: Level: intermediate
287: .seealso: STSetMatMode(), STMatMode
288: @*/
289: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
290: {
293: *mode = st->matmode;
294: return 0;
295: }
297: /*@
298: STSetTransform - Sets a flag to indicate whether the transformed matrices are
299: computed or not.
301: Logically Collective on st
303: Input Parameters:
304: + st - the spectral transformation context
305: - flg - the boolean flag
307: Options Database Key:
308: . -st_transform <bool> - Activate/deactivate the computation of matrices.
310: Notes:
311: This flag is intended for the case of polynomial eigenproblems solved
312: via linearization. If this flag is off (default) the spectral transformation
313: is applied to the linearization (handled by the eigensolver), otherwise
314: it is applied to the original problem.
316: Level: developer
318: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
319: @*/
320: PetscErrorCode STSetTransform(ST st,PetscBool flg)
321: {
324: if (st->transform != flg) {
325: st->transform = flg;
326: st->state = ST_STATE_INITIAL;
327: st->opready = PETSC_FALSE;
328: }
329: return 0;
330: }
332: /*@
333: STGetTransform - Gets a flag that that indicates whether the transformed
334: matrices are computed or not.
336: Not Collective
338: Input Parameter:
339: . st - the spectral transformation context
341: Output Parameter:
342: . flg - the flag
344: Level: developer
346: .seealso: STSetTransform()
347: @*/
348: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
349: {
352: *flg = st->transform;
353: return 0;
354: }