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: }