Line data Source code
1 : /*
2 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3 : SLEPc - Scalable Library for Eigenvalue Problem Computations
4 : Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
5 :
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 : */
13 :
14 : #include <slepc/private/stimpl.h> /*I "slepcst.h" I*/
15 :
16 : PetscBool STRegisterAllCalled = PETSC_FALSE;
17 : PetscFunctionList STList = NULL;
18 :
19 : /*@C
20 : STSetType - Builds ST for a particular spectral transformation.
21 :
22 : Logically Collective
23 :
24 : Input Parameters:
25 : + st - the spectral transformation context.
26 : - type - a known type
27 :
28 : Options Database Key:
29 : . -st_type <type> - Sets ST type
30 :
31 : Use -help for a list of available transformations
32 :
33 : Notes:
34 : See "slepc/include/slepcst.h" for available transformations
35 :
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.
40 :
41 : Level: beginner
42 :
43 : .seealso: EPSSetType()
44 :
45 : @*/
46 1094 : PetscErrorCode STSetType(ST st,STType type)
47 : {
48 1094 : PetscErrorCode (*r)(ST);
49 1094 : PetscBool match;
50 :
51 1094 : PetscFunctionBegin;
52 1094 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
53 1094 : PetscAssertPointer(type,2);
54 :
55 1094 : PetscCall(PetscObjectTypeCompare((PetscObject)st,type,&match));
56 1094 : if (match) PetscFunctionReturn(PETSC_SUCCESS);
57 1014 : STCheckNotSeized(st,1);
58 :
59 1014 : PetscCall(PetscFunctionListFind(STList,type,&r));
60 1014 : PetscCheck(r,PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
61 :
62 1014 : PetscTryTypeMethod(st,destroy);
63 1014 : PetscCall(PetscMemzero(st->ops,sizeof(struct _STOps)));
64 :
65 1014 : st->state = ST_STATE_INITIAL;
66 1014 : st->opready = PETSC_FALSE;
67 1014 : PetscCall(PetscObjectChangeTypeName((PetscObject)st,type));
68 1014 : PetscCall((*r)(st));
69 1014 : PetscFunctionReturn(PETSC_SUCCESS);
70 : }
71 :
72 : /*@C
73 : STGetType - Gets the ST type name (as a string) from the ST context.
74 :
75 : Not Collective
76 :
77 : Input Parameter:
78 : . st - the spectral transformation context
79 :
80 : Output Parameter:
81 : . type - name of the spectral transformation
82 :
83 : Level: intermediate
84 :
85 : .seealso: STSetType()
86 :
87 : @*/
88 91 : PetscErrorCode STGetType(ST st,STType *type)
89 : {
90 91 : PetscFunctionBegin;
91 91 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
92 91 : PetscAssertPointer(type,2);
93 91 : *type = ((PetscObject)st)->type_name;
94 91 : PetscFunctionReturn(PETSC_SUCCESS);
95 : }
96 :
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.
101 :
102 : Collective
103 :
104 : Input Parameter:
105 : . st - the spectral transformation context
106 :
107 : Level: beginner
108 :
109 : .seealso: STSetOptionsPrefix()
110 : @*/
111 778 : PetscErrorCode STSetFromOptions(ST st)
112 : {
113 778 : PetscScalar s;
114 778 : char type[256];
115 778 : PetscBool flg,bval;
116 778 : STMatMode mode;
117 778 : MatStructure mstr;
118 :
119 778 : PetscFunctionBegin;
120 778 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
121 778 : PetscCall(STRegisterAll());
122 2334 : PetscObjectOptionsBegin((PetscObject)st);
123 1533 : PetscCall(PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg));
124 778 : if (flg) PetscCall(STSetType(st,type));
125 626 : else if (!((PetscObject)st)->type_name) PetscCall(STSetType(st,STSHIFT));
126 :
127 778 : PetscCall(PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg));
128 778 : if (flg) PetscCall(STSetShift(st,s));
129 :
130 778 : PetscCall(PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg));
131 778 : if (flg) PetscCall(STSetMatMode(st,mode));
132 :
133 778 : PetscCall(PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg));
134 778 : if (flg) PetscCall(STSetMatStructure(st,mstr));
135 :
136 778 : PetscCall(PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg));
137 778 : if (flg) PetscCall(STSetTransform(st,bval));
138 :
139 778 : PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
140 778 : PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject));
141 778 : PetscOptionsEnd();
142 :
143 778 : if (st->usesksp) {
144 762 : PetscCall(STSetDefaultKSP(st));
145 762 : PetscCall(KSPSetFromOptions(st->ksp));
146 : }
147 778 : PetscFunctionReturn(PETSC_SUCCESS);
148 : }
149 :
150 : /*@
151 : STSetMatStructure - Sets an internal MatStructure attribute to
152 : indicate which is the relation of the sparsity pattern of all ST matrices.
153 :
154 : Logically Collective
155 :
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
160 :
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'.
166 :
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.
173 :
174 : This function has no effect in the case of standard eigenproblems.
175 :
176 : In case of polynomial eigenproblems, the flag applies to all matrices
177 : relative to the first one.
178 :
179 : Level: advanced
180 :
181 : .seealso: STSetMatrices(), MatAXPY()
182 : @*/
183 2 : PetscErrorCode STSetMatStructure(ST st,MatStructure str)
184 : {
185 2 : PetscFunctionBegin;
186 2 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
187 8 : PetscValidLogicalCollectiveEnum(st,str,2);
188 2 : switch (str) {
189 2 : case SAME_NONZERO_PATTERN:
190 : case DIFFERENT_NONZERO_PATTERN:
191 : case SUBSET_NONZERO_PATTERN:
192 : case UNKNOWN_NONZERO_PATTERN:
193 2 : st->str = str;
194 2 : break;
195 0 : default:
196 0 : SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
197 : }
198 2 : PetscFunctionReturn(PETSC_SUCCESS);
199 : }
200 :
201 : /*@
202 : STGetMatStructure - Gets the internal MatStructure attribute to
203 : indicate which is the relation of the sparsity pattern of the matrices.
204 :
205 : Not Collective
206 :
207 : Input Parameters:
208 : . st - the spectral transformation context
209 :
210 : Output Parameters:
211 : . str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
212 : SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN
213 :
214 : Level: advanced
215 :
216 : .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
217 : @*/
218 1148 : PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
219 : {
220 1148 : PetscFunctionBegin;
221 1148 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
222 1148 : PetscAssertPointer(str,2);
223 1148 : *str = st->str;
224 1148 : PetscFunctionReturn(PETSC_SUCCESS);
225 : }
226 :
227 : /*@
228 : STSetMatMode - Sets a flag to indicate how the transformed matrices are
229 : being stored in the spectral transformations.
230 :
231 : Logically Collective
232 :
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
237 :
238 : Options Database Key:
239 : . -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
240 : 'copy', 'inplace', 'shell' (see explanation below).
241 :
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).
245 :
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).
251 :
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).
257 :
258 : In the two first modes the efficiency of the computation
259 : can be controlled with STSetMatStructure().
260 :
261 : Level: intermediate
262 :
263 : .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
264 : @*/
265 70 : PetscErrorCode STSetMatMode(ST st,STMatMode mode)
266 : {
267 70 : PetscFunctionBegin;
268 70 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
269 280 : PetscValidLogicalCollectiveEnum(st,mode,2);
270 70 : if (st->matmode != mode) {
271 62 : STCheckNotSeized(st,1);
272 62 : st->matmode = mode;
273 62 : st->state = ST_STATE_INITIAL;
274 62 : st->opready = PETSC_FALSE;
275 : }
276 70 : PetscFunctionReturn(PETSC_SUCCESS);
277 : }
278 :
279 : /*@
280 : STGetMatMode - Gets a flag that indicates how the transformed matrices
281 : are stored in spectral transformations.
282 :
283 : Not Collective
284 :
285 : Input Parameter:
286 : . st - the spectral transformation context
287 :
288 : Output Parameter:
289 : . mode - the mode flag
290 :
291 : Level: intermediate
292 :
293 : .seealso: STSetMatMode(), STMatMode
294 : @*/
295 837 : PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
296 : {
297 837 : PetscFunctionBegin;
298 837 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
299 837 : PetscAssertPointer(mode,2);
300 837 : *mode = st->matmode;
301 837 : PetscFunctionReturn(PETSC_SUCCESS);
302 : }
303 :
304 : /*@
305 : STSetTransform - Sets a flag to indicate whether the transformed matrices are
306 : computed or not.
307 :
308 : Logically Collective
309 :
310 : Input Parameters:
311 : + st - the spectral transformation context
312 : - flg - the boolean flag
313 :
314 : Options Database Key:
315 : . -st_transform <bool> - Activate/deactivate the computation of matrices.
316 :
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.
322 :
323 : Level: developer
324 :
325 : .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
326 : @*/
327 977 : PetscErrorCode STSetTransform(ST st,PetscBool flg)
328 : {
329 977 : PetscFunctionBegin;
330 977 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
331 3908 : PetscValidLogicalCollectiveBool(st,flg,2);
332 977 : if (st->transform != flg) {
333 672 : st->transform = flg;
334 672 : st->state = ST_STATE_INITIAL;
335 672 : st->opready = PETSC_FALSE;
336 : }
337 977 : PetscFunctionReturn(PETSC_SUCCESS);
338 : }
339 :
340 : /*@
341 : STGetTransform - Gets a flag that indicates whether the transformed
342 : matrices are computed or not.
343 :
344 : Not Collective
345 :
346 : Input Parameter:
347 : . st - the spectral transformation context
348 :
349 : Output Parameter:
350 : . flg - the flag
351 :
352 : Level: developer
353 :
354 : .seealso: STSetTransform()
355 : @*/
356 12927 : PetscErrorCode STGetTransform(ST st,PetscBool *flg)
357 : {
358 12927 : PetscFunctionBegin;
359 12927 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
360 12927 : PetscAssertPointer(flg,2);
361 12927 : *flg = st->transform;
362 12927 : PetscFunctionReturn(PETSC_SUCCESS);
363 : }
|
