Actual source code: stfunc.c

  2: /*
  3:     The ST (spectral transformation) interface routines, callable by users.
  4: */

 6:  #include src/st/stimpl.h

 10: /*@C
 11:    STDestroy - Destroys ST context that was created with STCreate().

 13:    Collective on ST

 15:    Input Parameter:
 16: .  st - the spectral transformation context

 18:    Level: beginner

 20: .seealso: STCreate(), STSetUp()
 21: @*/
 22: int STDestroy(ST st)
 23: {

 28:   if (--st->refct > 0) return(0);

 30:   /* if memory was published with AMS then destroy it */
 31:   PetscObjectDepublish(st);

 33:   if (st->ops->destroy) { (*st->ops->destroy)(st); }
 34:   if (st->ksp) { KSPDestroy(st->ksp); }

 36:   PetscLogObjectDestroy(st);
 37:   PetscHeaderDestroy(st);
 38:   return(0);
 39: }

 43: static int STPublish_Petsc(PetscObject object)
 44: {
 45: #if defined(PETSC_HAVE_AMS)
 46:   ST          v = (ST) object;
 47:   int         ierr;
 48: #endif
 49: 

 52: #if defined(PETSC_HAVE_AMS)
 53:   /* if it is already published then return */
 54:   if (v->amem >=0 ) return(0);

 56:   PetscObjectPublishBaseBegin(object);
 57:   PetscObjectPublishBaseEnd(object);
 58: #endif

 60:   return(0);
 61: }

 65: /*@C
 66:    STCreate - Creates a spectral transformation context.

 68:    Collective on MPI_Comm

 70:    Input Parameter:
 71: .  comm - MPI communicator 

 73:    Output Parameter:
 74: .  st - location to put the spectral transformation context

 76:    Level: beginner

 78: .seealso: STSetUp(), STApply(), STDestroy()
 79: @*/
 80: int STCreate(MPI_Comm comm,ST *newst)
 81: {
 82:   ST      st;
 83:   int     ierr;

 86:   *newst = 0;

 88:   PetscHeaderCreate(st,_p_ST,struct _STOps,ST_COOKIE,-1,"ST",comm,STDestroy,STView);
 89:   PetscLogObjectCreate(st);
 90:   st->bops->publish       = STPublish_Petsc;
 91:   st->ops->destroy        = 0;
 92:   st->ops->apply          = 0;
 93:   st->ops->applyB         = STDefaultApplyB;
 94:   st->ops->applynoB       = 0;
 95:   st->ops->setshift       = 0;
 96:   st->ops->view           = 0;

 98:   st->A                   = 0;
 99:   st->B                   = 0;
100:   st->sigma               = 0.0;
101:   st->vec                 = 0;
102:   st->ksp                 = 0;
103:   st->data                = 0;
104:   st->setupcalled         = 0;
105:   *newst                  = st;
106:   PetscPublishAll(st);
107:   return(0);

109: }

113: /*@
114:    STSetOperators - Sets the matrices associated with the eigenvalue problem. 

116:    Collective on ST and Mat

118:    Input Parameters:
119: +  st - the spectral transformation context
120: .  A  - the matrix associated with the eigensystem
121: -  B  - the second matrix in the case of generalized eigenproblems

123:    Notes:
124:    To specify a standard eigenproblem, use PETSC_NULL for B.

126:    Level: intermediate

128: .seealso: STGetOperators()
129:  @*/
130: int STSetOperators(ST st,Mat A,Mat B)
131: {
136:   st->A = A;
137:   st->B = B;
138:   st->setupcalled = 0;
139:   return(0);
140: }

144: /*@C
145:    STGetOperators - Gets the matrices associated with the eigensystem.

147:    Not collective, though parallel Mats are returned if the ST is parallel

149:    Input Parameter:
150: .  st - the spectral transformation context

152:    Output Parameters:
153: .  A - the matrix associated with the eigensystem
154: -  B - the second matrix in the case of generalized eigenproblems

156:    Level: intermediate

158: .seealso: STSetOperators()
159: @*/
160: int STGetOperators(ST st,Mat *A,Mat *B)
161: {
164:   if (A) *A = st->A;
165:   if (B) *B = st->B;
166:   return(0);
167: }

171: /*@
172:    STSetVector - Sets a vector associated with the ST object.

174:    Collective on ST and Vec

176:    Input Parameters:
177: +  st  - the spectral transformation context
178: -  vec - the vector

180:    Notes:
181:    The vector must be set so that the ST object knows what type
182:    of vector to allocate if necessary.

184:    Level: intermediate

186: .seealso: STGetVector()

188: @*/
189: int STSetVector(ST st,Vec vec)
190: {
195:   st->vec = vec;
196:   return(0);
197: }

201: /*@
202:    STGetVector - Gets a vector associated with the ST object; if the 
203:    vector was not yet set it will return a nul pointer.

205:    Not collective, but vector is shared by all processors that share the ST

207:    Input Parameter:
208: .  st - the spectral transformation context

210:    Output Parameter:
211: .  vec - the vector

213:    Level: intermediate

215: .seealso: STSetVector()

217: @*/
218: int STGetVector(ST st,Vec *vec)
219: {
222:   *vec = st->vec;
223:   return(0);
224: }

228: /*@
229:    STSetShift - Sets the shift associated with the spectral transformation

231:    Not collective

233:    Input Parameters:
234: +  st - the spectral transformation context
235: -  shift - the value of the shift

237:    Note:
238:    In some spectral transformations, changing the shift may have associated
239:    a lot of work, for example recomputing a factorization.
240:    
241:    Level: beginner

243: @*/
244: int STSetShift(ST st,PetscScalar shift)
245: {
246:   int         ierr;

250:   if (st->sigma != shift) {
251:     if (st->ops->setshift) {
252:       (*st->ops->setshift)(st,shift);
253:     }
254:   }
255:   st->sigma = shift;
256:   return(0);
257: }

261: /*@
262:    STGetShift - Gets the shift associated with the spectral transformation.

264:    Not collective

266:    Input Parameter:
267: .  st - the spectral transformation context

269:    Output Parameter:
270: .  shift - the value of the shift

272:    Level: beginner

274: @*/
275: int STGetShift(ST st,PetscScalar* shift)
276: {
279:   if (shift)  *shift = st->sigma;
280:   return(0);
281: }

285: /*@
286:    STGetNumberOfShifts - Returns the number of shifts used in this
287:    spectral transformation type.

289:    Not collective

291:    Input Parameter:
292: .  st - the spectral transformation context

294:    Output Parameter:
295: .  nshifts - the number of shifts

297:    Level: advanced

299: @*/
300: int STGetNumberOfShifts(ST st,int* nshifts)
301: {
304:   if (nshifts)  *nshifts = st->numberofshifts;
305:   return(0);
306: }

310: /*@C
311:    STSetOptionsPrefix - Sets the prefix used for searching for all 
312:    ST options in the database.

314:    Collective on ST

316:    Input Parameters:
317: +  st     - the spectral transformation context
318: -  prefix - the prefix string to prepend to all ST option requests

320:    Notes:
321:    A hyphen (-) must NOT be given at the beginning of the prefix name.
322:    The first character of all runtime options is AUTOMATICALLY the
323:    hyphen.

325:    Level: advanced

327: .seealso: STAppendOptionsPrefix(), STGetOptionsPrefix()
328: @*/
329: int STSetOptionsPrefix(ST st,char *prefix)
330: {

335:   PetscObjectSetOptionsPrefix((PetscObject)st, prefix);
336:   return(0);
337: }

341: /*@C
342:    STAppendOptionsPrefix - Appends to the prefix used for searching for all 
343:    ST options in the database.

345:    Collective on ST

347:    Input Parameters:
348: +  st     - the spectral transformation context
349: -  prefix - the prefix string to prepend to all ST option requests

351:    Notes:
352:    A hyphen (-) must NOT be given at the beginning of the prefix name.
353:    The first character of all runtime options is AUTOMATICALLY the
354:    hyphen.

356:    Level: advanced

358: .seealso: STSetOptionsPrefix(), STGetOptionsPrefix()
359: @*/
360: int STAppendOptionsPrefix(ST st,char *prefix)
361: {

366:   PetscObjectAppendOptionsPrefix((PetscObject)st, prefix);
367:   return(0);
368: }

372: /*@C
373:    STGetOptionsPrefix - Gets the prefix used for searching for all 
374:    ST options in the database.

376:    Not Collective

378:    Input Parameters:
379: .  st - the spectral transformation context

381:    Output Parameters:
382: .  prefix - pointer to the prefix string used, is returned

384:    Notes: On the Fortran side, the user should pass in a string 'prefix' of
385:    sufficient length to hold the prefix.

387:    Level: advanced

389: .seealso: STSetOptionsPrefix(), STAppendOptionsPrefix()
390: @*/
391: int STGetOptionsPrefix(ST st,char **prefix)
392: {

397:   PetscObjectGetOptionsPrefix((PetscObject)st, prefix);
398:   return(0);
399: }

403: /*@C
404:    STView - Prints the ST data structure.

406:    Collective on ST

408:    Input Parameters:
409: +  ST - the ST context
410: -  viewer - optional visualization context

412:    Note:
413:    The available visualization contexts include
414: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
415: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
416:          output where only the first processor opens
417:          the file.  All other processors send their 
418:          data to the first processor to print. 

420:    The user can open an alternative visualization contexts with
421:    PetscViewerASCIIOpen() (output to a specified file).

423:    Level: beginner

425: .seealso: EPSView(), PetscViewerASCIIOpen()
426: @*/
427: int STView(ST st,PetscViewer viewer)
428: {
429:   STType            cstr;
430:   int               ierr;
431:   PetscTruth        isascii,isstring;
432:   PetscViewerFormat format;

436:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(st->comm);

440:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);
441:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_STRING,&isstring);
442:   if (isascii) {
443:     PetscViewerGetFormat(viewer,&format);
444:     PetscViewerASCIIPrintf(viewer,"ST Object:\n");
445:     STGetType(st,&cstr);
446:     if (cstr) {
447:       PetscViewerASCIIPrintf(viewer,"  type: %s\n",cstr);
448:     } else {
449:       PetscViewerASCIIPrintf(viewer,"  type: not yet set\n");
450:     }
451:     if (st->numberofshifts>0) {
452: #if !defined(PETSC_USE_COMPLEX)
453:       PetscViewerASCIIPrintf(viewer,"  shift: %g\n",st->sigma);
454: #else
455:       PetscViewerASCIIPrintf(viewer,"  shift: %g+%g i\n",PetscRealPart(st->sigma),PetscImaginaryPart(st->sigma));
456: #endif
457:     }
458:     if (st->ops->view) {
459:       PetscViewerASCIIPushTab(viewer);
460:       (*st->ops->view)(st,viewer);
461:       PetscViewerASCIIPopTab(viewer);
462:     }
463:     if (st->ksp) {
464:       PetscViewerASCIIPushTab(viewer);
465:       PetscViewerASCIIPrintf(viewer,"Associated KSP object\n");
466:       PetscViewerASCIIPrintf(viewer,"------------------------------\n");
467:       KSPView(st->ksp,viewer);
468:       PetscViewerASCIIPrintf(viewer,"------------------------------\n");
469:       PetscViewerASCIIPopTab(viewer);
470:     }
471:   } else if (isstring) {
472:     STGetType(st,&cstr);
473:     PetscViewerStringSPrintf(viewer," %-7.7s",cstr);
474:     if (st->ksp) {KSPView(st->ksp,viewer);}
475:     if (st->ops->view) {(*st->ops->view)(st,viewer);}
476:   } else {
477:     SETERRQ1(1,"Viewer type %s not supported by ST",((PetscObject)viewer)->type_name);
478:   }
479:   return(0);
480: }

482: /*MC
483:    STRegisterDynamic - Adds a method to the spectral transformation package.

485:    Synopsis:
486:    STRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(ST))

488:    Not collective

490:    Input Parameters:
491: +  name_solver - name of a new user-defined solver
492: .  path - path (either absolute or relative) the library containing this solver
493: .  name_create - name of routine to create method context
494: -  routine_create - routine to create method context

496:    Notes:
497:    STRegisterDynamic() may be called multiple times to add several user-defined spectral transformations.

499:    If dynamic libraries are used, then the fourth input argument (routine_create)
500:    is ignored.

502:    Sample usage:
503: .vb
504:    STRegisterDynamic("my_solver","/home/username/my_lib/lib/libO/solaris/mylib.a",
505:               "MySolverCreate",MySolverCreate);
506: .ve

508:    Then, your solver can be chosen with the procedural interface via
509: $     STSetType(st,"my_solver")
510:    or at runtime via the option
511: $     -st_type my_solver

513:    Level: advanced

515:    $SLEPC_DIR, $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.

517: .seealso: STRegisterAll(), STRegisterDestroy(), STRegister()
518: M*/

522: int STRegister(char *sname,char *path,char *name,int (*function)(ST))
523: {
524:   int  ierr;
525:   char fullname[256];

528:   PetscFListConcat(path,name,fullname);
529:   PetscFListAdd(&STList,sname,fullname,(void (*)(void))function);
530:   return(0);
531: }