Actual source code: stset.c

  1: /*
  2:     Routines to set ST methods and options.

  4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  6:    Copyright (c) 2002-2013, 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: intermediate

 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->setupcalled = 0;
 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:   if (!STRegisterAllCalled) { STRegisterAll(); }
136:   PetscObjectOptionsBegin((PetscObject)st);
137:     PetscOptionsList("-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","Shift matrix mode","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:     if (st->ops->setfromoptions) {
166:       (*st->ops->setfromoptions)(st);
167:     }
168:     PetscObjectProcessOptionsHandlers((PetscObject)st);
169:   PetscOptionsEnd();
170:   if (!st->ksp) { STGetKSP(st,&st->ksp); }
171:   KSPSetFromOptions(st->ksp);
172:   return(0);
173: }

177: /*@
178:    STSetMatStructure - Sets an internal MatStructure attribute to
179:    indicate which is the relation of the sparsity pattern of the two matrices
180:    A and B constituting the generalized eigenvalue problem.

182:    Logically Collective on ST

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

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

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

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

202:    Level: advanced

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

225: /*@
226:    STGetMatStructure - Gets the internal MatStructure attribute to
227:    indicate which is the relation of the sparsity pattern of the two matrices
228:    A and B constituting the generalized eigenvalue problem.

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:    Note:
240:    This function has no effect in the case of standard eigenproblems.

242:    Level: advanced

244: .seealso: STSetMatStructure(), STSetOperators(), MatAXPY()
245: @*/
246: PetscErrorCode STGetMatStructure(ST st,MatStructure *str)
247: {
251:   *str = st->str;
252:   return(0);
253: }

257: /*@
258:    STSetMatMode - Sets a flag to indicate how the matrix is
259:    being shifted in the shift-and-invert and Cayley spectral transformations.

261:    Logically Collective on ST

263:    Input Parameters:
264: +  st - the spectral transformation context
265: -  mode - the mode flag, one of ST_MATMODE_COPY,
266:           ST_MATMODE_INPLACE or ST_MATMODE_SHELL

268:    Options Database Key:
269: .  -st_matmode <mode> - Indicates the mode flag, where <mode> is one of
270:           'copy', 'inplace' or 'shell' (see explanation below).

272:    Notes:
273:    By default (ST_MATMODE_COPY), a copy of matrix A is made and then
274:    this copy is shifted explicitly, e.g. A <- (A - s B).

276:    With ST_MATMODE_INPLACE, the original matrix A is shifted at
277:    STSetUp() and unshifted at the end of the computations. With respect to
278:    the previous one, this mode avoids a copy of matrix A. However, a
279:    backdraw is that the recovered matrix might be slightly different
280:    from the original one (due to roundoff).

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

288:    In the case of generalized problems, in the two first modes the matrix
289:    A - s B has to be computed explicitly. The efficiency of this computation
290:    can be controlled with STSetMatStructure().

292:    Level: intermediate

294: .seealso: STSetOperators(), STSetMatStructure(), STGetMatMode(), STMatMode
295: @*/
296: PetscErrorCode STSetMatMode(ST st,STMatMode mode)
297: {
301:   st->shift_matrix = mode;
302:   st->setupcalled = 0;
303:   return(0);
304: }

308: /*@C
309:    STGetMatMode - Gets a flag that indicates how the matrix is being
310:    shifted in the shift-and-invert and Cayley spectral transformations.

312:    Not Collective

314:    Input Parameter:
315: .  st - the spectral transformation context

317:    Output Parameter:
318: .  mode - the mode flag

320:    Level: intermediate

322: .seealso: STSetMatMode(), STMatMode
323: @*/
324: PetscErrorCode STGetMatMode(ST st,STMatMode *mode)
325: {
329:   *mode = st->shift_matrix;
330:   return(0);
331: }