Actual source code: stset.c
slepc-3.21.1 2024-04-26
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
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;
51: PetscFunctionBegin;
53: PetscAssertPointer(type,2);
55: PetscCall(PetscObjectTypeCompare((PetscObject)st,type,&match));
56: if (match) PetscFunctionReturn(PETSC_SUCCESS);
57: STCheckNotSeized(st,1);
59: PetscCall(PetscFunctionListFind(STList,type,&r));
60: PetscCheck(r,PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
62: PetscTryTypeMethod(st,destroy);
63: PetscCall(PetscMemzero(st->ops,sizeof(struct _STOps)));
65: st->state = ST_STATE_INITIAL;
66: st->opready = PETSC_FALSE;
67: PetscCall(PetscObjectChangeTypeName((PetscObject)st,type));
68: PetscCall((*r)(st));
69: PetscFunctionReturn(PETSC_SUCCESS);
70: }
72: /*@C
73: STGetType - Gets the ST type name (as a string) from the ST context.
75: Not Collective
77: Input Parameter:
78: . st - the spectral transformation context
80: Output Parameter:
81: . type - name of the spectral transformation
83: Level: intermediate
85: .seealso: STSetType()
87: @*/
88: PetscErrorCode STGetType(ST st,STType *type)
89: {
90: PetscFunctionBegin;
92: PetscAssertPointer(type,2);
93: *type = ((PetscObject)st)->type_name;
94: PetscFunctionReturn(PETSC_SUCCESS);
95: }
97: /*@
98: STSetFromOptions - Sets ST options from the options database.
99: This routine must be called before STSetUp() if the user is to be
100: allowed to set the type of transformation.
102: Collective
104: Input Parameter:
105: . st - the spectral transformation context
107: Level: beginner
109: .seealso: STSetOptionsPrefix()
110: @*/
111: PetscErrorCode STSetFromOptions(ST st)
112: {
113: PetscScalar s;
114: char type[256];
115: PetscBool flg,bval;
116: STMatMode mode;
117: MatStructure mstr;
119: PetscFunctionBegin;
121: PetscCall(STRegisterAll());
122: PetscObjectOptionsBegin((PetscObject)st);
123: PetscCall(PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg));
124: if (flg) PetscCall(STSetType(st,type));
125: else if (!((PetscObject)st)->type_name) PetscCall(STSetType(st,STSHIFT));
127: PetscCall(PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg));
128: if (flg) PetscCall(STSetShift(st,s));
130: PetscCall(PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg));
131: if (flg) PetscCall(STSetMatMode(st,mode));
133: PetscCall(PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg));
134: if (flg) PetscCall(STSetMatStructure(st,mstr));
136: PetscCall(PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg));
137: if (flg) PetscCall(STSetTransform(st,bval));
139: PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
140: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject));
141: PetscOptionsEnd();
143: if (st->usesksp) {
144: PetscCall(STSetDefaultKSP(st));
145: PetscCall(KSPSetFromOptions(st->ksp));
146: }
147: PetscFunctionReturn(PETSC_SUCCESS);
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
156: Input Parameters:
157: + st - the spectral transformation context
158: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
159: SUBSET_NONZERO_PATTERN, or UNKNOWN_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), 'subset' (pattern is a subset of the
165: first one), or 'unknown'.
167: Notes:
168: If the sparsity pattern of the second matrix is equal or a subset of the
169: pattern of the first matrix then it is recommended to set this attribute
170: for efficiency reasons (in particular, for internal MatAXPY() operations).
171: If not set, the default is UNKNOWN_NONZERO_PATTERN, in which case the patterns
172: will be compared to determine if they are equal.
174: This function has no effect in the case of standard eigenproblems.
176: In case of polynomial eigenproblems, the flag applies to all matrices
177: relative to the first one.
179: Level: advanced
181: .seealso: STSetMatrices(), MatAXPY()
182: @*/
183: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
184: {
185: PetscFunctionBegin;
188: switch (str) {
189: case SAME_NONZERO_PATTERN:
190: case DIFFERENT_NONZERO_PATTERN:
191: case SUBSET_NONZERO_PATTERN:
192: case UNKNOWN_NONZERO_PATTERN:
193: st->str = str;
194: break;
195: default:
196: SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
197: }
198: PetscFunctionReturn(PETSC_SUCCESS);
199: }
201: /*@
202: STGetMatStructure - Gets the internal MatStructure attribute to
203: indicate which is the relation of the sparsity pattern of the matrices.
205: Not Collective
207: Input Parameters:
208: . st - the spectral transformation context
210: Output Parameters:
211: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
212: SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
214: Level: advanced
216: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
217: @*/
218: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
219: {
220: PetscFunctionBegin;
222: PetscAssertPointer(str,2);
223: *str = st->str;
224: PetscFunctionReturn(PETSC_SUCCESS);
225: }
227: /*@
228: STSetMatMode - Sets a flag to indicate how the transformed matrices are
229: being stored in the spectral transformations.
231: Logically Collective
233: Input Parameters:
234: + st - the spectral transformation context
235: - mode - the mode flag, one of ST_MATMODE_COPY,
236: ST_MATMODE_INPLACE, or ST_MATMODE_SHELL
238: Options Database Key:
239: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
240: 'copy', 'inplace', 'shell' (see explanation below).
242: Notes:
243: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
244: this copy is modified explicitly, e.g. A <- (A - s B).
246: With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
247: and changes are reverted at the end of the computations. With respect to
248: the previous one, this mode avoids a copy of matrix A. However, a
249: drawback is that the recovered matrix might be slightly different
250: from the original one (due to roundoff).
252: With ST_MATMODE_SHELL, the solver works with an implicit shell
253: matrix that represents the shifted matrix. This mode is the most efficient
254: in creating the shifted matrix but it places serious limitations to the
255: linear solves performed in each iteration of the eigensolver (typically,
256: only iterative solvers with Jacobi preconditioning can be used).
258: In the two first modes the efficiency of the computation
259: can be controlled with STSetMatStructure().
261: Level: intermediate
263: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
264: @*/
265: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
266: {
267: PetscFunctionBegin;
270: if (st->matmode != mode) {
271: STCheckNotSeized(st,1);
272: st->matmode = mode;
273: st->state = ST_STATE_INITIAL;
274: st->opready = PETSC_FALSE;
275: }
276: PetscFunctionReturn(PETSC_SUCCESS);
277: }
279: /*@
280: STGetMatMode - Gets a flag that indicates how the transformed matrices
281: are stored in spectral transformations.
283: Not Collective
285: Input Parameter:
286: . st - the spectral transformation context
288: Output Parameter:
289: . mode - the mode flag
291: Level: intermediate
293: .seealso: STSetMatMode(), STMatMode
294: @*/
295: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
296: {
297: PetscFunctionBegin;
299: PetscAssertPointer(mode,2);
300: *mode = st->matmode;
301: PetscFunctionReturn(PETSC_SUCCESS);
302: }
304: /*@
305: STSetTransform - Sets a flag to indicate whether the transformed matrices are
306: computed or not.
308: Logically Collective
310: Input Parameters:
311: + st - the spectral transformation context
312: - flg - the boolean flag
314: Options Database Key:
315: . -st_transform <bool> - Activate/deactivate the computation of matrices.
317: Notes:
318: This flag is intended for the case of polynomial eigenproblems solved
319: via linearization. If this flag is off (default) the spectral transformation
320: is applied to the linearization (handled by the eigensolver), otherwise
321: it is applied to the original problem.
323: Level: developer
325: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
326: @*/
327: PetscErrorCode STSetTransform(ST st,PetscBool flg)
328: {
329: PetscFunctionBegin;
332: if (st->transform != flg) {
333: st->transform = flg;
334: st->state = ST_STATE_INITIAL;
335: st->opready = PETSC_FALSE;
336: }
337: PetscFunctionReturn(PETSC_SUCCESS);
338: }
340: /*@
341: STGetTransform - Gets a flag that indicates whether the transformed
342: matrices are computed or not.
344: Not Collective
346: Input Parameter:
347: . st - the spectral transformation context
349: Output Parameter:
350: . flg - the flag
352: Level: developer
354: .seealso: STSetTransform()
355: @*/
356: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
357: {
358: PetscFunctionBegin;
360: PetscAssertPointer(flg,2);
361: *flg = st->transform;
362: PetscFunctionReturn(PETSC_SUCCESS);
363: }