Actual source code: stset.c

slepc-3.16.2 2022-02-01
Report Typos and Errors
  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_SHELL

243:    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 iterative 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(), STMatMode
269: @*/
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(), STMatMode
299: @*/
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: }