Actual source code: stset.c

slepc-3.22.0 2024-09-28
Report Typos and Errors
  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: /*@
 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: /*@
 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: }

365: /*@
366:    STSetStructured - Sets a flag to indicate that the application of the
367:    operator must be done taking into account its structure.

369:    Logically Collective

371:    Input Parameters:
372: +  st  - the spectral transformation context
373: -  flg - the boolean flag

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.

379:    Level: developer

381: .seealso: STApply(), STGetStructured()
382: @*/
383: PetscErrorCode STSetStructured(ST st,PetscBool flg)
384: {
385:   PetscFunctionBegin;
388:   if (st->structured != flg) {
389:     st->structured = flg;
390:     st->state      = ST_STATE_INITIAL;
391:     st->opready    = PETSC_FALSE;
392:   }
393:   PetscFunctionReturn(PETSC_SUCCESS);
394: }

396: /*@
397:    STGetStructured - Gets a flag that indicates if the application of the
398:    operator is done using its structure.

400:    Not Collective

402:    Input Parameter:
403: .  st - the spectral transformation context

405:    Output Parameter:
406: .  flg - the flag

408:    Level: developer

410: .seealso: STSetStructured()
411: @*/
412: PetscErrorCode STGetStructured(ST st,PetscBool *flg)
413: {
414:   PetscFunctionBegin;
416:   PetscAssertPointer(flg,2);
417:   *flg = st->structured;
418:   PetscFunctionReturn(PETSC_SUCCESS);
419: }