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 : /*@
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 1126 : PetscErrorCode STSetType(ST st,STType type)
47 : {
48 1126 : PetscErrorCode (*r)(ST);
49 1126 : PetscBool match;
50 :
51 1126 : PetscFunctionBegin;
52 1126 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
53 1126 : PetscAssertPointer(type,2);
54 :
55 1126 : PetscCall(PetscObjectTypeCompare((PetscObject)st,type,&match));
56 1126 : if (match) PetscFunctionReturn(PETSC_SUCCESS);
57 1042 : STCheckNotSeized(st,1);
58 :
59 1042 : PetscCall(PetscFunctionListFind(STList,type,&r));
60 1042 : PetscCheck(r,PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);
61 :
62 1042 : PetscTryTypeMethod(st,destroy);
63 1042 : PetscCall(PetscMemzero(st->ops,sizeof(struct _STOps)));
64 :
65 1042 : st->state = ST_STATE_INITIAL;
66 1042 : st->opready = PETSC_FALSE;
67 1042 : PetscCall(PetscObjectChangeTypeName((PetscObject)st,type));
68 1042 : PetscCall((*r)(st));
69 1042 : PetscFunctionReturn(PETSC_SUCCESS);
70 : }
71 :
72 : /*@
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 79 : PetscErrorCode STGetType(ST st,STType *type)
89 : {
90 79 : PetscFunctionBegin;
91 79 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
92 79 : PetscAssertPointer(type,2);
93 79 : *type = ((PetscObject)st)->type_name;
94 79 : 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 808 : PetscErrorCode STSetFromOptions(ST st)
112 : {
113 808 : PetscScalar s;
114 808 : char type[256];
115 808 : PetscBool flg,bval;
116 808 : STMatMode mode;
117 808 : MatStructure mstr;
118 :
119 808 : PetscFunctionBegin;
120 808 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
121 808 : PetscCall(STRegisterAll());
122 2424 : PetscObjectOptionsBegin((PetscObject)st);
123 1596 : PetscCall(PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg));
124 808 : if (flg) PetscCall(STSetType(st,type));
125 649 : else if (!((PetscObject)st)->type_name) PetscCall(STSetType(st,STSHIFT));
126 :
127 808 : PetscCall(PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg));
128 808 : if (flg) PetscCall(STSetShift(st,s));
129 :
130 808 : PetscCall(PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg));
131 808 : if (flg) PetscCall(STSetMatMode(st,mode));
132 :
133 808 : PetscCall(PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg));
134 808 : if (flg) PetscCall(STSetMatStructure(st,mstr));
135 :
136 808 : PetscCall(PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg));
137 808 : if (flg) PetscCall(STSetTransform(st,bval));
138 :
139 808 : PetscTryTypeMethod(st,setfromoptions,PetscOptionsObject);
140 808 : PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)st,PetscOptionsObject));
141 808 : PetscOptionsEnd();
142 :
143 808 : if (st->usesksp) {
144 792 : PetscCall(STSetDefaultKSP(st));
145 792 : PetscCall(KSPSetFromOptions(st->ksp));
146 : }
147 808 : 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 6 : PetscErrorCode STSetMatStructure(ST st,MatStructure str)
184 : {
185 6 : PetscFunctionBegin;
186 6 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
187 18 : PetscValidLogicalCollectiveEnum(st,str,2);
188 6 : switch (str) {
189 6 : case SAME_NONZERO_PATTERN:
190 : case DIFFERENT_NONZERO_PATTERN:
191 : case SUBSET_NONZERO_PATTERN:
192 : case UNKNOWN_NONZERO_PATTERN:
193 6 : st->str = str;
194 6 : break;
195 0 : default:
196 0 : SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
197 : }
198 6 : 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 325 : PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
219 : {
220 325 : PetscFunctionBegin;
221 325 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
222 325 : PetscAssertPointer(str,2);
223 325 : *str = st->str;
224 325 : 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 71 : PetscErrorCode STSetMatMode(ST st,STMatMode mode)
266 : {
267 71 : PetscFunctionBegin;
268 71 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
269 213 : PetscValidLogicalCollectiveEnum(st,mode,2);
270 71 : if (st->matmode != mode) {
271 65 : STCheckNotSeized(st,1);
272 65 : st->matmode = mode;
273 65 : st->state = ST_STATE_INITIAL;
274 65 : st->opready = PETSC_FALSE;
275 : }
276 71 : 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 893 : PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
296 : {
297 893 : PetscFunctionBegin;
298 893 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
299 893 : PetscAssertPointer(mode,2);
300 893 : *mode = st->matmode;
301 893 : 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 1021 : PetscErrorCode STSetTransform(ST st,PetscBool flg)
328 : {
329 1021 : PetscFunctionBegin;
330 1021 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
331 3063 : PetscValidLogicalCollectiveBool(st,flg,2);
332 1021 : if (st->transform != flg) {
333 723 : st->transform = flg;
334 723 : st->state = ST_STATE_INITIAL;
335 723 : st->opready = PETSC_FALSE;
336 : }
337 1021 : 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 11064 : PetscErrorCode STGetTransform(ST st,PetscBool *flg)
357 : {
358 11064 : PetscFunctionBegin;
359 11064 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
360 11064 : PetscAssertPointer(flg,2);
361 11064 : *flg = st->transform;
362 11064 : PetscFunctionReturn(PETSC_SUCCESS);
363 : }
364 :
365 : /*@
366 : STSetStructured - Sets a flag to indicate that the application of the
367 : operator must be done taking into account its structure.
368 :
369 : Logically Collective
370 :
371 : Input Parameters:
372 : + st - the spectral transformation context
373 : - flg - the boolean flag
374 :
375 : Note:
376 : This flag is intended for the case of structured eigenproblems. It is set
377 : internally by the solver, the user should not modify its value.
378 :
379 : Level: developer
380 :
381 : .seealso: STApply(), STGetStructured()
382 : @*/
383 922 : PetscErrorCode STSetStructured(ST st,PetscBool flg)
384 : {
385 922 : PetscFunctionBegin;
386 922 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
387 2766 : PetscValidLogicalCollectiveBool(st,flg,2);
388 922 : if (st->structured != flg) {
389 20 : st->structured = flg;
390 20 : st->state = ST_STATE_INITIAL;
391 20 : st->opready = PETSC_FALSE;
392 : }
393 922 : PetscFunctionReturn(PETSC_SUCCESS);
394 : }
395 :
396 : /*@
397 : STGetStructured - Gets a flag that indicates if the application of the
398 : operator is done using its structure.
399 :
400 : Not Collective
401 :
402 : Input Parameter:
403 : . st - the spectral transformation context
404 :
405 : Output Parameter:
406 : . flg - the flag
407 :
408 : Level: developer
409 :
410 : .seealso: STSetStructured()
411 : @*/
412 0 : PetscErrorCode STGetStructured(ST st,PetscBool *flg)
413 : {
414 0 : PetscFunctionBegin;
415 0 : PetscValidHeaderSpecific(st,ST_CLASSID,1);
416 0 : PetscAssertPointer(flg,2);
417 0 : *flg = st->structured;
418 0 : PetscFunctionReturn(PETSC_SUCCESS);
419 : }
|
