Actual source code: pf.c
petsc-3.5.4 2015-05-23
1: /*
2: The PF mathematical functions interface routines, callable by users.
3: */
4: #include <../src/vec/pf/pfimpl.h> /*I "petscpf.h" I*/
6: PetscClassId PF_CLASSID = 0;
7: PetscFunctionList PFList = NULL; /* list of all registered PD functions */
8: PetscBool PFRegisterAllCalled = PETSC_FALSE;
12: /*@C
13: PFSet - Sets the C/C++/Fortran functions to be used by the PF function
15: Collective on PF
17: Input Parameter:
18: + pf - the function context
19: . apply - function to apply to an array
20: . applyvec - function to apply to a Vec
21: . view - function that prints information about the PF
22: . destroy - function to free the private function context
23: - ctx - private function context
25: Level: beginner
27: .keywords: PF, setting
29: .seealso: PFCreate(), PFDestroy(), PFSetType(), PFApply(), PFApplyVec()
30: @*/
31: PetscErrorCode PFSet(PF pf,PetscErrorCode (*apply)(void*,PetscInt,const PetscScalar*,PetscScalar*),PetscErrorCode (*applyvec)(void*,Vec,Vec),PetscErrorCode (*view)(void*,PetscViewer),PetscErrorCode (*destroy)(void*),void*ctx)
32: {
35: pf->data = ctx;
36: pf->ops->destroy = destroy;
37: pf->ops->apply = apply;
38: pf->ops->applyvec = applyvec;
39: pf->ops->view = view;
40: return(0);
41: }
45: /*@C
46: PFDestroy - Destroys PF context that was created with PFCreate().
48: Collective on PF
50: Input Parameter:
51: . pf - the function context
53: Level: beginner
55: .keywords: PF, destroy
57: .seealso: PFCreate(), PFSet(), PFSetType()
58: @*/
59: PetscErrorCode PFDestroy(PF *pf)
60: {
64: if (!*pf) return(0);
66: if (--((PetscObject)(*pf))->refct > 0) return(0);
68: PFViewFromOptions(*pf,NULL,"-pf_view");
69: /* if memory was published with SAWs then destroy it */
70: PetscObjectSAWsViewOff((PetscObject)*pf);
72: if ((*pf)->ops->destroy) { (*(*pf)->ops->destroy)((*pf)->data);}
73: PetscHeaderDestroy(pf);
74: return(0);
75: }
79: /*@C
80: PFCreate - Creates a mathematical function context.
82: Collective on MPI_Comm
84: Input Parameter:
85: + comm - MPI communicator
86: . dimin - dimension of the space you are mapping from
87: - dimout - dimension of the space you are mapping to
89: Output Parameter:
90: . pf - the function context
92: Level: developer
94: .keywords: PF, create, context
96: .seealso: PFSet(), PFApply(), PFDestroy(), PFApplyVec()
97: @*/
98: PetscErrorCode PFCreate(MPI_Comm comm,PetscInt dimin,PetscInt dimout,PF *pf)
99: {
100: PF newpf;
105: *pf = NULL;
106: PFInitializePackage();
108: PetscHeaderCreate(newpf,_p_PF,struct _PFOps,PF_CLASSID,"PF","Mathematical functions","Vec",comm,PFDestroy,PFView);
109: newpf->data = 0;
110: newpf->ops->destroy = 0;
111: newpf->ops->apply = 0;
112: newpf->ops->applyvec = 0;
113: newpf->ops->view = 0;
114: newpf->dimin = dimin;
115: newpf->dimout = dimout;
117: *pf = newpf;
118: return(0);
120: }
122: /* -------------------------------------------------------------------------------*/
126: /*@
127: PFApplyVec - Applies the mathematical function to a vector
129: Collective on PF
131: Input Parameters:
132: + pf - the function context
133: - x - input vector (or NULL for the vector (0,1, .... N-1)
135: Output Parameter:
136: . y - output vector
138: Level: beginner
140: .keywords: PF, apply
142: .seealso: PFApply(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
143: @*/
144: PetscErrorCode PFApplyVec(PF pf,Vec x,Vec y)
145: {
147: PetscInt i,rstart,rend,n,p;
148: PetscBool nox = PETSC_FALSE;
153: if (x) {
155: if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different vectors");
156: } else {
157: PetscScalar *xx;
158: PetscInt lsize;
160: VecGetLocalSize(y,&lsize);
161: lsize = pf->dimin*lsize/pf->dimout;
162: VecCreateMPI(PetscObjectComm((PetscObject)y),lsize,PETSC_DETERMINE,&x);
163: nox = PETSC_TRUE;
164: VecGetOwnershipRange(x,&rstart,&rend);
165: VecGetArray(x,&xx);
166: for (i=rstart; i<rend; i++) xx[i-rstart] = (PetscScalar)i;
167: VecRestoreArray(x,&xx);
168: }
170: VecGetLocalSize(x,&n);
171: VecGetLocalSize(y,&p);
172: if ((pf->dimin*(n/pf->dimin)) != n) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local input vector length %D not divisible by dimin %D of function",n,pf->dimin);
173: if ((pf->dimout*(p/pf->dimout)) != p) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local output vector length %D not divisible by dimout %D of function",p,pf->dimout);
174: if ((n/pf->dimin) != (p/pf->dimout)) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local vector lengths %D %D are wrong for dimin and dimout %D %D of function",n,p,pf->dimin,pf->dimout);
176: if (pf->ops->applyvec) {
177: (*pf->ops->applyvec)(pf->data,x,y);
178: } else {
179: PetscScalar *xx,*yy;
181: VecGetLocalSize(x,&n);
182: n = n/pf->dimin;
183: VecGetArray(x,&xx);
184: VecGetArray(y,&yy);
185: if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");
186: (*pf->ops->apply)(pf->data,n,xx,yy);
187: VecRestoreArray(x,&xx);
188: VecRestoreArray(y,&yy);
189: }
190: if (nox) {
191: VecDestroy(&x);
192: }
193: return(0);
194: }
198: /*@
199: PFApply - Applies the mathematical function to an array of values.
201: Collective on PF
203: Input Parameters:
204: + pf - the function context
205: . n - number of pointwise function evaluations to perform, each pointwise function evaluation
206: is a function of dimin variables and computes dimout variables where dimin and dimout are defined
207: in the call to PFCreate()
208: - x - input array
210: Output Parameter:
211: . y - output array
213: Level: beginner
215: Notes:
217: .keywords: PF, apply
219: .seealso: PFApplyVec(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
220: @*/
221: PetscErrorCode PFApply(PF pf,PetscInt n,const PetscScalar *x,PetscScalar *y)
222: {
229: if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different arrays");
230: if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");
232: (*pf->ops->apply)(pf->data,n,x,y);
233: return(0);
234: }
238: /*@
239: PFView - Prints information about a mathematical function
241: Collective on PF unless PetscViewer is PETSC_VIEWER_STDOUT_SELF
243: Input Parameters:
244: + PF - the PF context
245: - viewer - optional visualization context
247: Note:
248: The available visualization contexts include
249: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
250: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
251: output where only the first processor opens
252: the file. All other processors send their
253: data to the first processor to print.
255: The user can open an alternative visualization contexts with
256: PetscViewerASCIIOpen() (output to a specified file).
258: Level: developer
260: .keywords: PF, view
262: .seealso: PetscViewerCreate(), PetscViewerASCIIOpen()
263: @*/
264: PetscErrorCode PFView(PF pf,PetscViewer viewer)
265: {
266: PetscErrorCode ierr;
267: PetscBool iascii;
268: PetscViewerFormat format;
272: if (!viewer) {
273: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)pf),&viewer);
274: }
278: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
279: if (iascii) {
280: PetscViewerGetFormat(viewer,&format);
281: PetscObjectPrintClassNamePrefixType((PetscObject)pf,viewer);
282: if (pf->ops->view) {
283: PetscViewerASCIIPushTab(viewer);
284: (*pf->ops->view)(pf->data,viewer);
285: PetscViewerASCIIPopTab(viewer);
286: }
287: }
288: return(0);
289: }
294: /*@C
295: PFRegister - Adds a method to the mathematical function package.
297: Not collective
299: Input Parameters:
300: + name_solver - name of a new user-defined solver
301: - routine_create - routine to create method context
303: Notes:
304: PFRegister() may be called multiple times to add several user-defined functions
306: Sample usage:
307: .vb
308: PFRegister("my_function",MyFunctionSetCreate);
309: .ve
311: Then, your solver can be chosen with the procedural interface via
312: $ PFSetType(pf,"my_function")
313: or at runtime via the option
314: $ -pf_type my_function
316: Level: advanced
318: .keywords: PF, register
320: .seealso: PFRegisterAll(), PFRegisterDestroy(), PFRegister()
321: @*/
322: PetscErrorCode PFRegister(const char sname[],PetscErrorCode (*function)(PF,void*))
323: {
327: PetscFunctionListAdd(&PFList,sname,function);
328: return(0);
329: }
333: /*@C
334: PFGetType - Gets the PF method type and name (as a string) from the PF
335: context.
337: Not Collective
339: Input Parameter:
340: . pf - the function context
342: Output Parameter:
343: . type - name of function
345: Level: intermediate
347: .keywords: PF, get, method, name, type
349: .seealso: PFSetType()
351: @*/
352: PetscErrorCode PFGetType(PF pf,PFType *type)
353: {
357: *type = ((PetscObject)pf)->type_name;
358: return(0);
359: }
364: /*@C
365: PFSetType - Builds PF for a particular function
367: Collective on PF
369: Input Parameter:
370: + pf - the function context.
371: . type - a known method
372: - ctx - optional type dependent context
374: Options Database Key:
375: . -pf_type <type> - Sets PF type
378: Notes:
379: See "petsc/include/petscpf.h" for available methods (for instance,
380: PFCONSTANT)
382: Level: intermediate
384: .keywords: PF, set, method, type
386: .seealso: PFSet(), PFRegister(), PFCreate(), DMDACreatePF()
388: @*/
389: PetscErrorCode PFSetType(PF pf,PFType type,void *ctx)
390: {
391: PetscErrorCode ierr,(*r)(PF,void*);
392: PetscBool match;
398: PetscObjectTypeCompare((PetscObject)pf,type,&match);
399: if (match) return(0);
401: if (pf->ops->destroy) { (*pf->ops->destroy)(pf);}
402: pf->data = 0;
404: /* Determine the PFCreateXXX routine for a particular function */
405: PetscFunctionListFind(PFList,type,&r);
406: if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PF type %s",type);
407: pf->ops->destroy = 0;
408: pf->ops->view = 0;
409: pf->ops->apply = 0;
410: pf->ops->applyvec = 0;
412: /* Call the PFCreateXXX routine for this particular function */
413: (*r)(pf,ctx);
415: PetscObjectChangeTypeName((PetscObject)pf,type);
416: return(0);
417: }
421: /*@
422: PFSetFromOptions - Sets PF options from the options database.
424: Collective on PF
426: Input Parameters:
427: . pf - the mathematical function context
429: Options Database Keys:
431: Notes:
432: To see all options, run your program with the -help option
433: or consult the users manual.
435: Level: intermediate
437: .keywords: PF, set, from, options, database
439: .seealso:
440: @*/
441: PetscErrorCode PFSetFromOptions(PF pf)
442: {
444: char type[256];
445: PetscBool flg;
450: PetscObjectOptionsBegin((PetscObject)pf);
451: PetscOptionsFList("-pf_type","Type of function","PFSetType",PFList,0,type,256,&flg);
452: if (flg) {
453: PFSetType(pf,type,NULL);
454: }
455: if (pf->ops->setfromoptions) {
456: (*pf->ops->setfromoptions)(pf);
457: }
459: /* process any options handlers added with PetscObjectAddOptionsHandler() */
460: PetscObjectProcessOptionsHandlers((PetscObject)pf);
461: PetscOptionsEnd();
462: return(0);
463: }
465: static PetscBool PFPackageInitialized = PETSC_FALSE;
468: /*@C
469: PFFinalizePackage - This function destroys everything in the Petsc interface to Mathematica. It is
470: called from PetscFinalize().
472: Level: developer
474: .keywords: Petsc, destroy, package, mathematica
475: .seealso: PetscFinalize()
476: @*/
477: PetscErrorCode PFFinalizePackage(void)
478: {
482: PetscFunctionListDestroy(&PFList);
483: PFPackageInitialized = PETSC_FALSE;
484: PFRegisterAllCalled = PETSC_FALSE;
485: return(0);
486: }
490: /*@C
491: PFInitializePackage - This function initializes everything in the PF package. It is called
492: from PetscDLLibraryRegister() when using dynamic libraries, and on the first call to PFCreate()
493: when using static libraries.
495: Level: developer
497: .keywords: Vec, initialize, package
498: .seealso: PetscInitialize()
499: @*/
500: PetscErrorCode PFInitializePackage(void)
501: {
502: char logList[256];
503: char *className;
504: PetscBool opt;
508: if (PFPackageInitialized) return(0);
509: PFPackageInitialized = PETSC_TRUE;
510: /* Register Classes */
511: PetscClassIdRegister("PointFunction",&PF_CLASSID);
512: /* Register Constructors */
513: PFRegisterAll();
514: /* Process info exclusions */
515: PetscOptionsGetString(NULL, "-info_exclude", logList, 256, &opt);
516: if (opt) {
517: PetscStrstr(logList, "pf", &className);
518: if (className) {
519: PetscInfoDeactivateClass(PF_CLASSID);
520: }
521: }
522: /* Process summary exclusions */
523: PetscOptionsGetString(NULL, "-log_summary_exclude", logList, 256, &opt);
524: if (opt) {
525: PetscStrstr(logList, "pf", &className);
526: if (className) {
527: PetscLogEventDeactivateClass(PF_CLASSID);
528: }
529: }
530: PetscRegisterFinalize(PFFinalizePackage);
531: return(0);
532: }