1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2021, 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 = 0;
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 ierr,(*r)(ST);
49: PetscBool match;
55: PetscObjectTypeCompare((PetscObject)st,type,&match);
56: if (match) return(0);
57: STCheckNotSeized(st,1);
59: PetscFunctionListFind(STList,type,&r);
60: if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
62: if (st->ops->destroy) { (*st->ops->destroy)(st); }
63: PetscMemzero(st->ops,sizeof(struct _STOps));
65: st->state = ST_STATE_INITIAL;
66: st->opready = PETSC_FALSE;
67: PetscObjectChangeTypeName((PetscObject)st,type);
68: (*r)(st);
69: return(0);
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: . name - name of the spectral transformation
83: Level: intermediate
85: .seealso: STSetType()
87: @*/
88: PetscErrorCode STGetType(ST st,STType *type) 89: {
93: *type = ((PetscObject)st)->type_name;
94: return(0);
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 on st
104: Input Parameter:
105: . st - the spectral transformation context
107: Level: beginner
108: @*/
109: PetscErrorCode STSetFromOptions(ST st)110: {
112: PetscScalar s;
113: char type[256];
114: PetscBool flg,bval;
115: const char *structure_list[4] = {"different","subset","same","unknown"};
116: STMatMode mode;
117: MatStructure mstr;
121: STRegisterAll();
122: PetscObjectOptionsBegin((PetscObject)st);
123: PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg);
124: if (flg) {
125: STSetType(st,type);
126: } else if (!((PetscObject)st)->type_name) {
127: STSetType(st,STSHIFT);
128: }
130: PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
131: if (flg) { STSetShift(st,s); }
133: PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg);
134: if (flg) { STSetMatMode(st,mode); }
136: PetscOptionsEList("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",structure_list,4,structure_list[st->str],(PetscInt*)&mstr,&flg);
137: if (flg) { STSetMatStructure(st,mstr); }
139: PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg);
140: if (flg) { STSetTransform(st,bval); }
142: if (st->ops->setfromoptions) {
143: (*st->ops->setfromoptions)(PetscOptionsObject,st);
144: }
145: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
146: PetscOptionsEnd();
148: if (st->usesksp) {
149: STSetDefaultKSP(st);
150: KSPSetFromOptions(st->ksp);
151: }
152: return(0);
153: }
155: /*@
156: STSetMatStructure - Sets an internal MatStructure attribute to
157: indicate which is the relation of the sparsity pattern of all ST matrices.
159: Logically Collective on st
161: Input Parameters:
162: + st - the spectral transformation context
163: - str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
164: SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
166: Options Database Key:
167: . -st_matstructure <str> - Indicates the structure flag, where <str> is one
168: of 'same' (matrices have the same nonzero pattern), 'different'
169: (different nonzero pattern), 'subset' (pattern is a subset of the
170: first one), or 'unknown'.
172: Notes:
173: If the sparsity pattern of the second matrix is equal or a subset of the
174: pattern of the first matrix then it is recommended to set this attribute
175: for efficiency reasons (in particular, for internal MatAXPY() operations).
176: If not set, the default is UNKNOWN_NONZERO_PATTERN, in which case the patterns
177: will be compared to determine if they are equal.
179: This function has no effect in the case of standard eigenproblems.
181: In case of polynomial eigenproblems, the flag applies to all matrices
182: relative to the first one.
184: Level: advanced
186: .seealso: STSetMatrices(), MatAXPY()
187: @*/
188: PetscErrorCode STSetMatStructure(ST st,MatStructure str)189: {
193: switch (str) {
194: case SAME_NONZERO_PATTERN:
195: case DIFFERENT_NONZERO_PATTERN:
196: case SUBSET_NONZERO_PATTERN:
197: case UNKNOWN_NONZERO_PATTERN:
198: st->str = str;
199: break;
200: default:201: SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
202: }
203: return(0);
204: }
206: /*@
207: STGetMatStructure - Gets the internal MatStructure attribute to
208: indicate which is the relation of the sparsity pattern of the matrices.
210: Not Collective
212: Input Parameters:
213: . st - the spectral transformation context
215: Output Parameters:
216: . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
217: SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
219: Level: advanced
221: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
222: @*/
223: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)224: {
228: *str = st->str;
229: return(0);
230: }
232: /*@
233: STSetMatMode - Sets a flag to indicate how the transformed matrices are
234: being stored in the spectral transformations.
236: Logically Collective on st
238: Input Parameters:
239: + st - the spectral transformation context
240: - mode - the mode flag, one of ST_MATMODE_COPY,
241: ST_MATMODE_INPLACE, or ST_MATMODE_SHELL243: Options Database Key:
244: . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
245: 'copy', 'inplace', 'shell' (see explanation below).
247: Notes:
248: By default (ST_MATMODE_COPY), a copy of matrix A is made and then
249: this copy is modified explicitly, e.g. A <- (A - s B).
251: With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
252: and changes are reverted at the end of the computations. With respect to
253: the previous one, this mode avoids a copy of matrix A. However, a
254: drawback is that the recovered matrix might be slightly different
255: from the original one (due to roundoff).
257: With ST_MATMODE_SHELL, the solver works with an implicit shell
258: matrix that represents the shifted matrix. This mode is the most efficient
259: in creating the shifted matrix but it places serious limitations to the
260: linear solves performed in each iteration of the eigensolver (typically,
261: only interative solvers with Jacobi preconditioning can be used).
263: In the two first modes the efficiency of the computation
264: can be controlled with STSetMatStructure().
266: Level: intermediate
268: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode269: @*/
270: PetscErrorCode STSetMatMode(ST st,STMatMode mode)271: {
275: if (st->matmode != mode) {
276: STCheckNotSeized(st,1);
277: st->matmode = mode;
278: st->state = ST_STATE_INITIAL;
279: st->opready = PETSC_FALSE;
280: }
281: return(0);
282: }
284: /*@
285: STGetMatMode - Gets a flag that indicates how the transformed matrices
286: are stored in spectral transformations.
288: Not Collective
290: Input Parameter:
291: . st - the spectral transformation context
293: Output Parameter:
294: . mode - the mode flag
296: Level: intermediate
298: .seealso: STSetMatMode(), STMatMode299: @*/
300: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)301: {
305: *mode = st->matmode;
306: return(0);
307: }
309: /*@
310: STSetTransform - Sets a flag to indicate whether the transformed matrices are
311: computed or not.
313: Logically Collective on st
315: Input Parameters:
316: + st - the spectral transformation context
317: - flg - the boolean flag
319: Options Database Key:
320: . -st_transform <bool> - Activate/deactivate the computation of matrices.
322: Notes:
323: This flag is intended for the case of polynomial eigenproblems solved
324: via linearization. If this flag is off (default) the spectral transformation
325: is applied to the linearization (handled by the eigensolver), otherwise
326: it is applied to the original problem.
328: Level: developer
330: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
331: @*/
332: PetscErrorCode STSetTransform(ST st,PetscBool flg)333: {
337: if (st->transform != flg) {
338: st->transform = flg;
339: st->state = ST_STATE_INITIAL;
340: st->opready = PETSC_FALSE;
341: }
342: return(0);
343: }
345: /*@
346: STGetTransform - Gets a flag that that indicates whether the transformed
347: matrices are computed or not.
349: Not Collective
351: Input Parameter:
352: . st - the spectral transformation context
354: Output Parameter:
355: . flg - the flag
357: Level: developer
359: .seealso: STSetTransform()
360: @*/
361: PetscErrorCode STGetTransform(ST st,PetscBool *flg)362: {
366: *flg = st->transform;
367: return(0);
368: }