Actual source code: pf.c
petsc-3.12.5 2020-03-29
1: /*
2: The PF mathematical functions interface routines, callable by users.
3: */
4: #include <../src/vec/pf/pfimpl.h>
6: PetscClassId PF_CLASSID = 0;
7: PetscFunctionList PFList = NULL; /* list of all registered PD functions */
8: PetscBool PFRegisterAllCalled = PETSC_FALSE;
10: /*@C
11: PFSet - Sets the C/C++/Fortran functions to be used by the PF function
13: Collective on PF
15: Input Parameter:
16: + pf - the function context
17: . apply - function to apply to an array
18: . applyvec - function to apply to a Vec
19: . view - function that prints information about the PF
20: . destroy - function to free the private function context
21: - ctx - private function context
23: Level: beginner
25: .seealso: PFCreate(), PFDestroy(), PFSetType(), PFApply(), PFApplyVec()
26: @*/
27: 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)
28: {
31: pf->data = ctx;
32: pf->ops->destroy = destroy;
33: pf->ops->apply = apply;
34: pf->ops->applyvec = applyvec;
35: pf->ops->view = view;
36: return(0);
37: }
39: /*@C
40: PFDestroy - Destroys PF context that was created with PFCreate().
42: Collective on PF
44: Input Parameter:
45: . pf - the function context
47: Level: beginner
49: .seealso: PFCreate(), PFSet(), PFSetType()
50: @*/
51: PetscErrorCode PFDestroy(PF *pf)
52: {
56: if (!*pf) return(0);
58: if (--((PetscObject)(*pf))->refct > 0) return(0);
60: PFViewFromOptions(*pf,NULL,"-pf_view");
61: /* if memory was published with SAWs then destroy it */
62: PetscObjectSAWsViewOff((PetscObject)*pf);
64: if ((*pf)->ops->destroy) { (*(*pf)->ops->destroy)((*pf)->data);}
65: PetscHeaderDestroy(pf);
66: return(0);
67: }
69: /*@C
70: PFCreate - Creates a mathematical function context.
72: Collective
74: Input Parameter:
75: + comm - MPI communicator
76: . dimin - dimension of the space you are mapping from
77: - dimout - dimension of the space you are mapping to
79: Output Parameter:
80: . pf - the function context
82: Level: developer
84: .seealso: PFSet(), PFApply(), PFDestroy(), PFApplyVec()
85: @*/
86: PetscErrorCode PFCreate(MPI_Comm comm,PetscInt dimin,PetscInt dimout,PF *pf)
87: {
88: PF newpf;
93: *pf = NULL;
94: PFInitializePackage();
96: PetscHeaderCreate(newpf,PF_CLASSID,"PF","Mathematical functions","Vec",comm,PFDestroy,PFView);
97: newpf->data = 0;
98: newpf->ops->destroy = 0;
99: newpf->ops->apply = 0;
100: newpf->ops->applyvec = 0;
101: newpf->ops->view = 0;
102: newpf->dimin = dimin;
103: newpf->dimout = dimout;
105: *pf = newpf;
106: return(0);
108: }
110: /* -------------------------------------------------------------------------------*/
112: /*@
113: PFApplyVec - Applies the mathematical function to a vector
115: Collective on PF
117: Input Parameters:
118: + pf - the function context
119: - x - input vector (or NULL for the vector (0,1, .... N-1)
121: Output Parameter:
122: . y - output vector
124: Level: beginner
126: .seealso: PFApply(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
127: @*/
128: PetscErrorCode PFApplyVec(PF pf,Vec x,Vec y)
129: {
131: PetscInt i,rstart,rend,n,p;
132: PetscBool nox = PETSC_FALSE;
137: if (x) {
139: if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different vectors");
140: } else {
141: PetscScalar *xx;
142: PetscInt lsize;
144: VecGetLocalSize(y,&lsize);
145: lsize = pf->dimin*lsize/pf->dimout;
146: VecCreateMPI(PetscObjectComm((PetscObject)y),lsize,PETSC_DETERMINE,&x);
147: nox = PETSC_TRUE;
148: VecGetOwnershipRange(x,&rstart,&rend);
149: VecGetArray(x,&xx);
150: for (i=rstart; i<rend; i++) xx[i-rstart] = (PetscScalar)i;
151: VecRestoreArray(x,&xx);
152: }
154: VecGetLocalSize(x,&n);
155: VecGetLocalSize(y,&p);
156: 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);
157: 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);
158: 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);
160: if (pf->ops->applyvec) {
161: (*pf->ops->applyvec)(pf->data,x,y);
162: } else {
163: PetscScalar *xx,*yy;
165: VecGetLocalSize(x,&n);
166: n = n/pf->dimin;
167: VecGetArray(x,&xx);
168: VecGetArray(y,&yy);
169: if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");
170: (*pf->ops->apply)(pf->data,n,xx,yy);
171: VecRestoreArray(x,&xx);
172: VecRestoreArray(y,&yy);
173: }
174: if (nox) {
175: VecDestroy(&x);
176: }
177: return(0);
178: }
180: /*@
181: PFApply - Applies the mathematical function to an array of values.
183: Collective on PF
185: Input Parameters:
186: + pf - the function context
187: . n - number of pointwise function evaluations to perform, each pointwise function evaluation
188: is a function of dimin variables and computes dimout variables where dimin and dimout are defined
189: in the call to PFCreate()
190: - x - input array
192: Output Parameter:
193: . y - output array
195: Level: beginner
197: Notes:
199: .seealso: PFApplyVec(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
200: @*/
201: PetscErrorCode PFApply(PF pf,PetscInt n,const PetscScalar *x,PetscScalar *y)
202: {
209: if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different arrays");
210: if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");
212: (*pf->ops->apply)(pf->data,n,x,y);
213: return(0);
214: }
216: /*@
217: PFView - Prints information about a mathematical function
219: Collective on PF unless PetscViewer is PETSC_VIEWER_STDOUT_SELF
221: Input Parameters:
222: + PF - the PF context
223: - viewer - optional visualization context
225: Note:
226: The available visualization contexts include
227: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
228: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
229: output where only the first processor opens
230: the file. All other processors send their
231: data to the first processor to print.
233: The user can open an alternative visualization contexts with
234: PetscViewerASCIIOpen() (output to a specified file).
236: Level: developer
238: .seealso: PetscViewerCreate(), PetscViewerASCIIOpen()
239: @*/
240: PetscErrorCode PFView(PF pf,PetscViewer viewer)
241: {
242: PetscErrorCode ierr;
243: PetscBool iascii;
244: PetscViewerFormat format;
248: if (!viewer) {
249: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)pf),&viewer);
250: }
254: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
255: if (iascii) {
256: PetscViewerGetFormat(viewer,&format);
257: PetscObjectPrintClassNamePrefixType((PetscObject)pf,viewer);
258: if (pf->ops->view) {
259: PetscViewerASCIIPushTab(viewer);
260: (*pf->ops->view)(pf->data,viewer);
261: PetscViewerASCIIPopTab(viewer);
262: }
263: }
264: return(0);
265: }
268: /*@C
269: PFRegister - Adds a method to the mathematical function package.
271: Not collective
273: Input Parameters:
274: + name_solver - name of a new user-defined solver
275: - routine_create - routine to create method context
277: Notes:
278: PFRegister() may be called multiple times to add several user-defined functions
280: Sample usage:
281: .vb
282: PFRegister("my_function",MyFunctionSetCreate);
283: .ve
285: Then, your solver can be chosen with the procedural interface via
286: $ PFSetType(pf,"my_function")
287: or at runtime via the option
288: $ -pf_type my_function
290: Level: advanced
292: .seealso: PFRegisterAll(), PFRegisterDestroy(), PFRegister()
293: @*/
294: PetscErrorCode PFRegister(const char sname[],PetscErrorCode (*function)(PF,void*))
295: {
299: PFInitializePackage();
300: PetscFunctionListAdd(&PFList,sname,function);
301: return(0);
302: }
304: /*@C
305: PFGetType - Gets the PF method type and name (as a string) from the PF
306: context.
308: Not Collective
310: Input Parameter:
311: . pf - the function context
313: Output Parameter:
314: . type - name of function
316: Level: intermediate
318: .seealso: PFSetType()
320: @*/
321: PetscErrorCode PFGetType(PF pf,PFType *type)
322: {
326: *type = ((PetscObject)pf)->type_name;
327: return(0);
328: }
331: /*@C
332: PFSetType - Builds PF for a particular function
334: Collective on PF
336: Input Parameter:
337: + pf - the function context.
338: . type - a known method
339: - ctx - optional type dependent context
341: Options Database Key:
342: . -pf_type <type> - Sets PF type
345: Notes:
346: See "petsc/include/petscpf.h" for available methods (for instance,
347: PFCONSTANT)
349: Level: intermediate
351: .seealso: PFSet(), PFRegister(), PFCreate(), DMDACreatePF()
353: @*/
354: PetscErrorCode PFSetType(PF pf,PFType type,void *ctx)
355: {
356: PetscErrorCode ierr,(*r)(PF,void*);
357: PetscBool match;
363: PetscObjectTypeCompare((PetscObject)pf,type,&match);
364: if (match) return(0);
366: if (pf->ops->destroy) { (*pf->ops->destroy)(pf);}
367: pf->data = 0;
369: /* Determine the PFCreateXXX routine for a particular function */
370: PetscFunctionListFind(PFList,type,&r);
371: if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PF type %s",type);
372: pf->ops->destroy = 0;
373: pf->ops->view = 0;
374: pf->ops->apply = 0;
375: pf->ops->applyvec = 0;
377: /* Call the PFCreateXXX routine for this particular function */
378: (*r)(pf,ctx);
380: PetscObjectChangeTypeName((PetscObject)pf,type);
381: return(0);
382: }
384: /*@
385: PFSetFromOptions - Sets PF options from the options database.
387: Collective on PF
389: Input Parameters:
390: . pf - the mathematical function context
392: Options Database Keys:
394: Notes:
395: To see all options, run your program with the -help option
396: or consult the users manual.
398: Level: intermediate
400: .seealso:
401: @*/
402: PetscErrorCode PFSetFromOptions(PF pf)
403: {
405: char type[256];
406: PetscBool flg;
411: PetscObjectOptionsBegin((PetscObject)pf);
412: PetscOptionsFList("-pf_type","Type of function","PFSetType",PFList,0,type,256,&flg);
413: if (flg) {
414: PFSetType(pf,type,NULL);
415: }
416: if (pf->ops->setfromoptions) {
417: (*pf->ops->setfromoptions)(PetscOptionsObject,pf);
418: }
420: /* process any options handlers added with PetscObjectAddOptionsHandler() */
421: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pf);
422: PetscOptionsEnd();
423: return(0);
424: }
426: static PetscBool PFPackageInitialized = PETSC_FALSE;
427: /*@C
428: PFFinalizePackage - This function destroys everything in the Petsc interface to Mathematica. It is
429: called from PetscFinalize().
431: Level: developer
433: .seealso: PetscFinalize()
434: @*/
435: PetscErrorCode PFFinalizePackage(void)
436: {
440: PetscFunctionListDestroy(&PFList);
441: PFPackageInitialized = PETSC_FALSE;
442: PFRegisterAllCalled = PETSC_FALSE;
443: return(0);
444: }
446: /*@C
447: PFInitializePackage - This function initializes everything in the PF package. It is called
448: from PetscDLLibraryRegister_petscvec() when using dynamic libraries, and on the first call to PFCreate()
449: when using shared or static libraries.
451: Level: developer
453: .seealso: PetscInitialize()
454: @*/
455: PetscErrorCode PFInitializePackage(void)
456: {
457: char logList[256];
458: PetscBool opt,pkg;
462: if (PFPackageInitialized) return(0);
463: PFPackageInitialized = PETSC_TRUE;
464: /* Register Classes */
465: PetscClassIdRegister("PointFunction",&PF_CLASSID);
466: /* Register Constructors */
467: PFRegisterAll();
468: /* Process info exclusions */
469: PetscOptionsGetString(NULL,NULL,"-info_exclude",logList,sizeof(logList),&opt);
470: if (opt) {
471: PetscStrInList("pf",logList,',',&pkg);
472: if (pkg) {PetscInfoDeactivateClass(PF_CLASSID);}
473: }
474: /* Process summary exclusions */
475: PetscOptionsGetString(NULL,NULL,"-log_exclude",logList,sizeof(logList),&opt);
476: if (opt) {
477: PetscStrInList("pf",logList,',',&pkg);
478: if (pkg) {PetscLogEventExcludeClass(PF_CLASSID);}
479: }
480: /* Register package finalizer */
481: PetscRegisterFinalize(PFFinalizePackage);
482: return(0);
483: }