Actual source code: stset.c

slepc-3.11.2 2019-07-30
Report Typos and Errors
  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-2019, 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>      /*I "slepcst.h" I*/

 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 Parameter:
 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);

 58:    PetscFunctionListFind(STList,type,&r);
 59:   if (!r) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested ST type %s",type);

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

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

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

 73:    Not Collective

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

 78:    Output Parameter:
 79: .  name - name of the spectral transformation

 81:    Level: intermediate

 83: .seealso: STSetType()

 85: @*/
 86: PetscErrorCode STGetType(ST st,STType *type)
 87: {
 91:   *type = ((PetscObject)st)->type_name;
 92:   return(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
106: @*/
107: PetscErrorCode STSetFromOptions(ST st)
108: {
110:   PetscScalar    s;
111:   char           type[256];
112:   PetscBool      flg;
113:   const char     *structure_list[3] = {"same","different","subset"};
114:   STMatMode      mode;
115:   MatStructure   mstr;

119:   STRegisterAll();
120:   PetscObjectOptionsBegin((PetscObject)st);
121:     PetscOptionsFList("-st_type","Spectral transformation","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
122:     if (flg) {
123:       STSetType(st,type);
124:     } else if (!((PetscObject)st)->type_name) {
125:       STSetType(st,STSHIFT);
126:     }

128:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
129:     if (flg) { STSetShift(st,s); }

131:     PetscOptionsEnum("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",STMatModes,(PetscEnum)st->shift_matrix,(PetscEnum*)&mode,&flg);
132:     if (flg) { STSetMatMode(st,mode); }

134:     PetscOptionsEList("-st_matstructure","Relation of the sparsity pattern of the matrices","STSetMatStructure",structure_list,3,structure_list[st->str],(PetscInt*)&mstr,&flg);
135:     if (flg) { STSetMatStructure(st,mstr); }

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

139:     if (st->ops->setfromoptions) {
140:       (*st->ops->setfromoptions)(PetscOptionsObject,st);
141:     }
142:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
143:   PetscOptionsEnd();

145:   STSetDefaultKSP(st);
146:   KSPSetFromOptions(st->ksp);
147:   return(0);
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 on ST

156:    Input Parameters:
157: +  st  - the spectral transformation context
158: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
159:          SUBSET_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) or 'subset' (pattern is a subset of the
165:          first one).

167:    Notes:
168:    By default, the sparsity patterns are assumed to be different. If the
169:    patterns are equal or a subset then it is recommended to set this attribute
170:    for efficiency reasons (in particular, for internal MatAXPY() operations).

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

174:    Level: advanced

176: .seealso: STSetMatrices(), MatAXPY()
177: @*/
178: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
179: {
183:   switch (str) {
184:     case SAME_NONZERO_PATTERN:
185:     case DIFFERENT_NONZERO_PATTERN:
186:     case SUBSET_NONZERO_PATTERN:
187:       st->str = str;
188:       break;
189:     default:
190:       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
191:   }
192:   return(0);
193: }

195: /*@
196:    STGetMatStructure - Gets the internal MatStructure attribute to
197:    indicate which is the relation of the sparsity pattern of the matrices.

199:    Not Collective

201:    Input Parameters:
202: .  st  - the spectral transformation context

204:    Output Parameters:
205: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
206:          SUBSET_NONZERO_PATTERN

208:    Level: advanced

210: .seealso: STSetMatStructure(), STSetMatrices(), MatAXPY()
211: @*/
212: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
213: {
217:   *str = st->str;
218:   return(0);
219: }

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

225:    Logically Collective on ST

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

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

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

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

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

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

255:    Level: intermediate

257: .seealso: STSetMatrices(), STSetMatStructure(), STGetMatMode(), STMatMode
258: @*/
259: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
260: {
264:   if (st->shift_matrix != mode) {
265:     st->shift_matrix = mode;
266:     st->state = ST_STATE_INITIAL;
267:   }
268:   return(0);
269: }

271: /*@
272:    STGetMatMode - Gets a flag that indicates how the transformed matrices
273:    are stored in spectral transformations.

275:    Not Collective

277:    Input Parameter:
278: .  st - the spectral transformation context

280:    Output Parameter:
281: .  mode - the mode flag

283:    Level: intermediate

285: .seealso: STSetMatMode(), STMatMode
286: @*/
287: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
288: {
292:   *mode = st->shift_matrix;
293:   return(0);
294: }

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

300:    Logically Collective on ST

302:    Input Parameters:
303: +  st  - the spectral transformation context
304: -  flg - the boolean flag

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

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

315:    Level: developer

317: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
318: @*/
319: PetscErrorCode STSetTransform(ST st,PetscBool flg)
320: {
324:   if (st->transform != flg) {
325:     st->transform = flg;
326:     st->state = ST_STATE_INITIAL;
327:   }
328:   return(0);
329: }

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

335:    Not Collective

337:    Input Parameter:
338: .  st - the spectral transformation context

340:    Output Parameter:
341: .  flg - the flag

343:    Level: developer

345: .seealso: STSetTransform()
346: @*/
347: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
348: {
352:   *flg = st->transform;
353:   return(0);
354: }