Actual source code: stset.c

slepc-3.17.1 2022-04-11
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 = 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 (*r)(ST);
 49:   PetscBool      match;


 54:   PetscObjectTypeCompare((PetscObject)st,type,&match);
 55:   if (match) PetscFunctionReturn(0);
 56:   STCheckNotSeized(st,1);

 58:   PetscFunctionListFind(STList,type,&r);

 61:   if (st->ops->destroy) (*st->ops->destroy)(st);
 62:   PetscMemzero(st->ops,sizeof(struct _STOps));

 64:   st->state   = ST_STATE_INITIAL;
 65:   st->opready = PETSC_FALSE;
 66:   PetscObjectChangeTypeName((PetscObject)st,type);
 67:   (*r)(st);
 68:   PetscFunctionReturn(0);
 69: }

 71: /*@C
 72:    STGetType - Gets the ST type name (as a string) from the ST context.

 74:    Not Collective

 76:    Input Parameter:
 77: .  st - the spectral transformation context

 79:    Output Parameter:
 80: .  type - name of the spectral transformation

 82:    Level: intermediate

 84: .seealso: STSetType()

 86: @*/
 87: PetscErrorCode STGetType(ST st,STType *type)
 88: {
 91:   *type = ((PetscObject)st)->type_name;
 92:   PetscFunctionReturn(0);
 93: }

 95: /*@
 96:    STSetFromOptions - Sets ST options from the options database.
 97:    This routine must be called before STSetUp() if the user is to be
 98:    allowed to set the type of transformation.

100:    Collective on st

102:    Input Parameter:
103: .  st - the spectral transformation context

105:    Level: beginner

107: .seealso: STSetOptionsPrefix()
108: @*/
109: PetscErrorCode STSetFromOptions(ST st)
110: {
112:   PetscScalar    s;
113:   char           type[256];
114:   PetscBool      flg,bval;
115:   STMatMode      mode;
116:   MatStructure   mstr;

119:   STRegisterAll();
120:   ierr = PetscObjectOptionsBegin((PetscObject)st);
121:     PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,sizeof(type),&flg);
122:     if (flg) STSetType(st,type);
123:     else if (!((PetscObject)st)->type_name) STSetType(st,STSHIFT);

125:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
126:     if (flg) STSetShift(st,s);

128:     PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->matmode,(PetscEnum*)&mode,&flg);
129:     if (flg) STSetMatMode(st,mode);

131:     PetscOptionsEnum("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",MatStructures,(PetscEnum)st->str,(PetscEnum*)&mstr,&flg);
132:     if (flg) STSetMatStructure(st,mstr);

134:     PetscOptionsBool("-st_transform","Whether transformed matrices are computed or not","STSetTransform",st->transform,&bval,&flg);
135:     if (flg) STSetTransform(st,bval);

137:     if (st->ops->setfromoptions) (*st->ops->setfromoptions)(PetscOptionsObject,st);
138:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
139:   ierr = PetscOptionsEnd();

141:   if (st->usesksp) {
142:     STSetDefaultKSP(st);
143:     KSPSetFromOptions(st->ksp);
144:   }
145:   PetscFunctionReturn(0);
146: }

148: /*@
149:    STSetMatStructure - Sets an internal MatStructure attribute to
150:    indicate which is the relation of the sparsity pattern of all ST matrices.

152:    Logically Collective on st

154:    Input Parameters:
155: +  st  - the spectral transformation context
156: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
157:          SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN

159:    Options Database Key:
160: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
161:          of 'same' (matrices have the same nonzero pattern), 'different'
162:          (different nonzero pattern), 'subset' (pattern is a subset of the
163:          first one), or 'unknown'.

165:    Notes:
166:    If the sparsity pattern of the second matrix is equal or a subset of the
167:    pattern of the first matrix then it is recommended to set this attribute
168:    for efficiency reasons (in particular, for internal MatAXPY() operations).
169:    If not set, the default is UNKNOWN_NONZERO_PATTERN, in which case the patterns
170:    will be compared to determine if they are equal.

172:    This function has no effect in the case of standard eigenproblems.

174:    In case of polynomial eigenproblems, the flag applies to all matrices
175:    relative to the first one.

177:    Level: advanced

179: .seealso: STSetMatrices(), MatAXPY()
180: @*/
181: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
182: {
185:   switch (str) {
186:     case SAME_NONZERO_PATTERN:
187:     case DIFFERENT_NONZERO_PATTERN:
188:     case SUBSET_NONZERO_PATTERN:
189:     case UNKNOWN_NONZERO_PATTERN:
190:       st->str = str;
191:       break;
192:     default:
193:       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
194:   }
195:   PetscFunctionReturn(0);
196: }

198: /*@
199:    STGetMatStructure - Gets the internal MatStructure attribute to
200:    indicate which is the relation of the sparsity pattern of the matrices.

202:    Not Collective

204:    Input Parameters:
205: .  st  - the spectral transformation context

207:    Output Parameters:
208: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN,
209:          SUBSET_NONZERO_PATTERN, or UNKNOWN_NONZERO_PATTERN

211:    Level: advanced

213: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
214: @*/
215: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
216: {
219:   *str = st->str;
220:   PetscFunctionReturn(0);
221: }

223: /*@
224:    STSetMatMode - Sets a flag to indicate how the transformed matrices are
225:    being stored in the spectral transformations.

227:    Logically Collective on st

229:    Input Parameters:
230: +  st - the spectral transformation context
231: -  mode - the mode flag, one of ST_MATMODE_COPY,
232:           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL

234:    Options Database Key:
235: .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
236:           'copy', 'inplace', 'shell' (see explanation below).

238:    Notes:
239:    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
240:    this copy is modified explicitly, e.g. A <- (A - s B).

242:    With ST_MATMODE_INPLACE, the original matrix A is modified at STSetUp()
243:    and changes are reverted at the end of the computations. With respect to
244:    the previous one, this mode avoids a copy of matrix A. However, a
245:    drawback is that the recovered matrix might be slightly different
246:    from the original one (due to roundoff).

248:    With ST_MATMODE_SHELL, the solver works with an implicit shell
249:    matrix that represents the shifted matrix. This mode is the most efficient
250:    in creating the shifted matrix but it places serious limitations to the
251:    linear solves performed in each iteration of the eigensolver (typically,
252:    only iterative solvers with Jacobi preconditioning can be used).

254:    In the two first modes the efficiency of the computation
255:    can be controlled with STSetMatStructure().

257:    Level: intermediate

259: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
260: @*/
261: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
262: {
265:   if (st->matmode != mode) {
266:     STCheckNotSeized(st,1);
267:     st->matmode = mode;
268:     st->state   = ST_STATE_INITIAL;
269:     st->opready = PETSC_FALSE;
270:   }
271:   PetscFunctionReturn(0);
272: }

274: /*@
275:    STGetMatMode - Gets a flag that indicates how the transformed matrices
276:    are stored in spectral transformations.

278:    Not Collective

280:    Input Parameter:
281: .  st - the spectral transformation context

283:    Output Parameter:
284: .  mode - the mode flag

286:    Level: intermediate

288: .seealso: STSetMatMode(), STMatMode
289: @*/
290: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
291: {
294:   *mode = st->matmode;
295:   PetscFunctionReturn(0);
296: }

298: /*@
299:    STSetTransform - Sets a flag to indicate whether the transformed matrices are
300:    computed or not.

302:    Logically Collective on st

304:    Input Parameters:
305: +  st  - the spectral transformation context
306: -  flg - the boolean flag

308:    Options Database Key:
309: .  -st_transform <bool> - Activate/deactivate the computation of matrices.

311:    Notes:
312:    This flag is intended for the case of polynomial eigenproblems solved
313:    via linearization. If this flag is off (default) the spectral transformation
314:    is applied to the linearization (handled by the eigensolver), otherwise
315:    it is applied to the original problem.

317:    Level: developer

319: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
320: @*/
321: PetscErrorCode STSetTransform(ST st,PetscBool flg)
322: {
325:   if (st->transform != flg) {
326:     st->transform = flg;
327:     st->state     = ST_STATE_INITIAL;
328:     st->opready   = PETSC_FALSE;
329:   }
330:   PetscFunctionReturn(0);
331: }

333: /*@
334:    STGetTransform - Gets a flag that that indicates whether the transformed
335:    matrices are computed or not.

337:    Not Collective

339:    Input Parameter:
340: .  st - the spectral transformation context

342:    Output Parameter:
343: .  flg - the flag

345:    Level: developer

347: .seealso: STSetTransform()
348: @*/
349: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
350: {
353:   *flg = st->transform;
354:   PetscFunctionReturn(0);
355: }