Actual source code: stset.c

slepc-3.7.2 2016-07-19
Report Typos and Errors
  1: /*
  2:     Routines to set ST methods and options.

  4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  6:    Copyright (c) 2002-2016, Universitat Politecnica de Valencia, Spain

  8:    This file is part of SLEPc.

 10:    SLEPc is free software: you can redistribute it and/or modify it under  the
 11:    terms of version 3 of the GNU Lesser General Public License as published by
 12:    the Free Software Foundation.

 14:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
 15:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
 16:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
 17:    more details.

 19:    You  should have received a copy of the GNU Lesser General  Public  License
 20:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
 21:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 22: */

 24: #include <slepc/private/stimpl.h>      /*I "slepcst.h" I*/

 26: PetscBool         STRegisterAllCalled = PETSC_FALSE;
 27: PetscFunctionList STList = 0;

 31: /*@C
 32:    STSetType - Builds ST for a particular spectral transformation.

 34:    Logically Collective on ST

 36:    Input Parameter:
 37: +  st   - the spectral transformation context.
 38: -  type - a known type

 40:    Options Database Key:
 41: .  -st_type <type> - Sets ST type

 43:    Use -help for a list of available transformations

 45:    Notes:
 46:    See "slepc/include/slepcst.h" for available transformations

 48:    Normally, it is best to use the EPSSetFromOptions() command and
 49:    then set the ST type from the options database rather than by using
 50:    this routine.  Using the options database provides the user with
 51:    maximum flexibility in evaluating the many different transformations.

 53:    Level: beginner

 55: .seealso: EPSSetType()

 57: @*/
 58: PetscErrorCode STSetType(ST st,STType type)
 59: {
 60:   PetscErrorCode ierr,(*r)(ST);
 61:   PetscBool      match;


 67:   PetscObjectTypeCompare((PetscObject)st,type,&match);
 68:   if (match) return(0);

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

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

 76:   st->state = ST_STATE_INITIAL;
 77:   PetscObjectChangeTypeName((PetscObject)st,type);
 78:   (*r)(st);
 79:   return(0);
 80: }

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

 87:    Not Collective

 89:    Input Parameter:
 90: .  st - the spectral transformation context

 92:    Output Parameter:
 93: .  name - name of the spectral transformation

 95:    Level: intermediate

 97: .seealso: STSetType()

 99: @*/
100: PetscErrorCode STGetType(ST st,STType *type)
101: {
105:   *type = ((PetscObject)st)->type_name;
106:   return(0);
107: }

111: /*@
112:    STSetFromOptions - Sets ST options from the options database.
113:    This routine must be called before STSetUp() if the user is to be
114:    allowed to set the type of transformation.

116:    Collective on ST

118:    Input Parameter:
119: .  st - the spectral transformation context

121:    Level: beginner
122: @*/
123: PetscErrorCode STSetFromOptions(ST st)
124: {
126:   PetscInt       i;
127:   PetscScalar    s;
128:   char           type[256];
129:   PetscBool      flg;
130:   const char     *mode_list[3] = {"copy","inplace","shell"};
131:   const char     *structure_list[3] = {"same","different","subset"};

135:   STRegisterAll();
136:   PetscObjectOptionsBegin((PetscObject)st);
137:     PetscOptionsFList("-st_type","Spectral Transformation type","STSetType",STList,(char*)(((PetscObject)st)->type_name?((PetscObject)st)->type_name:STSHIFT),type,256,&flg);
138:     if (flg) {
139:       STSetType(st,type);
140:     }
141:     /*
142:       Set the type if it was never set.
143:     */
144:     if (!((PetscObject)st)->type_name) {
145:       STSetType(st,STSHIFT);
146:     }

148:     PetscOptionsScalar("-st_shift","Value of the shift","STSetShift",st->sigma,&s,&flg);
149:     if (flg) {
150:       STSetShift(st,s);
151:     }

153:     PetscOptionsEList("-st_matmode","Matrix mode for transformed matrices","STSetMatMode",mode_list,3,mode_list[st->shift_matrix],&i,&flg);
154:     if (flg) st->shift_matrix = (STMatMode)i;

156:     PetscOptionsEList("-st_matstructure","Shift nonzero pattern","STSetMatStructure",structure_list,3,structure_list[st->str],&i,&flg);
157:     if (flg) {
158:       switch (i) {
159:         case 0: STSetMatStructure(st,SAME_NONZERO_PATTERN); break;
160:         case 1: STSetMatStructure(st,DIFFERENT_NONZERO_PATTERN); break;
161:         case 2: STSetMatStructure(st,SUBSET_NONZERO_PATTERN); break;
162:       }
163:     }

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

167:     if (st->ops->setfromoptions) {
168:       (*st->ops->setfromoptions)(PetscOptionsObject,st);
169:     }
170:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)st);
171:   PetscOptionsEnd();
172:   if (!st->ksp) { STGetKSP(st,&st->ksp); }
173:   KSPSetFromOptions(st->ksp);
174:   return(0);
175: }

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

183:    Logically Collective on ST

185:    Input Parameters:
186: +  st  - the spectral transformation context
187: -  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
188:          SUBSET_NONZERO_PATTERN

190:    Options Database Key:
191: .  -st_matstructure <str> - Indicates the structure flag, where <str> is one
192:          of 'same' (matrices have the same nonzero pattern), 'different'
193:          (different nonzero pattern) or 'subset' (pattern is a subset of the
194:          first one).

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

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

203:    Level: advanced

205: .seealso: STSetOperators(), MatAXPY()
206: @*/
207: PetscErrorCode STSetMatStructure(ST st,MatStructure str)
208: {
212:   switch (str) {
213:     case SAME_NONZERO_PATTERN:
214:     case DIFFERENT_NONZERO_PATTERN:
215:     case SUBSET_NONZERO_PATTERN:
216:       st->str = str;
217:       break;
218:     default:
219:       SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Invalid matrix structure flag");
220:   }
221:   return(0);
222: }

226: /*@
227:    STGetMatStructure - Gets the internal MatStructure attribute to
228:    indicate which is the relation of the sparsity pattern of the matrices.

230:    Not Collective

232:    Input Parameters:
233: .  st  - the spectral transformation context

235:    Output Parameters:
236: .  str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or
237:          SUBSET_NONZERO_PATTERN

239:    Level: advanced

241: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
242: @*/
243: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
244: {
248:   *str = st->str;
249:   return(0);
250: }

254: /*@
255:    STSetMatMode - Sets a flag to indicate how the transformed matrices are
256:    being stored in the spectral transformations.

258:    Logically Collective on ST

260:    Input Parameters:
261: +  st - the spectral transformation context
262: -  mode - the mode flag, one of ST_MATMODE_COPY,
263:           ST_MATMODE_INPLACE, or ST_MATMODE_SHELL

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

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

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

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

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

288:    Level: intermediate

290: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
291: @*/
292: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
293: {
297:   st->shift_matrix = mode;
298:   st->state = ST_STATE_INITIAL;
299:   return(0);
300: }

304: /*@
305:    STGetMatMode - Gets a flag that indicates how the transformed matrices
306:    are stored in spectral transformations.

308:    Not Collective

310:    Input Parameter:
311: .  st - the spectral transformation context

313:    Output Parameter:
314: .  mode - the mode flag

316:    Level: intermediate

318: .seealso: STSetMatMode(), STMatMode
319: @*/
320: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
321: {
325:   *mode = st->shift_matrix;
326:   return(0);
327: }

331: /*@
332:    STSetTransform - Sets a flag to indicate whether the transformed matrices are
333:    computed or not.

335:    Logically Collective on ST

337:    Input Parameters:
338: +  st  - the spectral transformation context
339: -  flg - the boolean flag

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

344:    Notes:
345:    This flag is intended for the case of polynomial eigenproblems solved
346:    via linearization. If this flag is off (default) the spectral transformation
347:    is applied to the linearization (handled by the eigensolver), otherwise
348:    it is applied to the original problem.

350:    Level: developer

352: .seealso: STMatSolve(), STMatMult(), STSetMatStructure(), STGetTransform()
353: @*/
354: PetscErrorCode STSetTransform(ST st,PetscBool flg)
355: {
359:   if (st->transform != flg) {
360:     st->transform = flg;
361:     st->state = ST_STATE_INITIAL;
362:   }
363:   return(0);
364: }

368: /*@
369:    STGetTransform - Gets a flag that that indicates whether the transformed
370:    matrices are computed or not.

372:    Not Collective

374:    Input Parameter:
375: .  st - the spectral transformation context

377:    Output Parameter:
378: .  flg - the flag

380:    Level: developer

382: .seealso: STSetTransform()
383: @*/
384: PetscErrorCode STGetTransform(ST st,PetscBool *flg)
385: {
389:   *flg = st->transform;
390:   return(0);
391: }