Actual source code: space.c
1: #include <petsc/private/petscfeimpl.h>
2: #include <petscdmshell.h>
4: PetscClassId PETSCSPACE_CLASSID = 0;
6: PetscFunctionList PetscSpaceList = NULL;
7: PetscBool PetscSpaceRegisterAllCalled = PETSC_FALSE;
9: /*@C
10: PetscSpaceRegister - Adds a new `PetscSpace` implementation
12: Not Collective, No Fortran Support
14: Input Parameters:
15: + sname - The name of a new user-defined creation routine
16: - function - The creation routine for the implementation type
18: Example Usage:
19: .vb
20: PetscSpaceRegister("my_space", MyPetscSpaceCreate);
21: .ve
23: Then, your PetscSpace type can be chosen with the procedural interface via
24: .vb
25: PetscSpaceCreate(MPI_Comm, PetscSpace *);
26: PetscSpaceSetType(PetscSpace, "my_space");
27: .ve
28: or at runtime via the option
29: .vb
30: -petscspace_type my_space
31: .ve
33: Level: advanced
35: Note:
36: `PetscSpaceRegister()` may be called multiple times to add several user-defined types of `PetscSpace`. The creation function is called
37: when the type is set to 'name'.
39: .seealso: `PetscSpace`, `PetscSpaceRegisterAll()`, `PetscSpaceRegisterDestroy()`
40: @*/
41: PetscErrorCode PetscSpaceRegister(const char sname[], PetscErrorCode (*function)(PetscSpace))
42: {
43: PetscFunctionBegin;
44: PetscCall(PetscFunctionListAdd(&PetscSpaceList, sname, function));
45: PetscFunctionReturn(PETSC_SUCCESS);
46: }
48: /*@
49: PetscSpaceSetType - Builds a particular `PetscSpace`
51: Collective
53: Input Parameters:
54: + sp - The `PetscSpace` object
55: - name - The kind of space
57: Options Database Key:
58: . -petscspace_type type - Sets the `PetscSpace` type; use -help for a list of available types
60: Level: intermediate
62: .seealso: `PetscSpace`, `PetscSpaceType`, `PetscSpaceGetType()`, `PetscSpaceCreate()`
63: @*/
64: PetscErrorCode PetscSpaceSetType(PetscSpace sp, PetscSpaceType name)
65: {
66: PetscErrorCode (*r)(PetscSpace);
67: PetscBool match;
69: PetscFunctionBegin;
71: PetscCall(PetscObjectTypeCompare((PetscObject)sp, name, &match));
72: if (match) PetscFunctionReturn(PETSC_SUCCESS);
74: PetscCall(PetscSpaceRegisterAll());
75: PetscCall(PetscFunctionListFind(PetscSpaceList, name, &r));
76: PetscCheck(r, PetscObjectComm((PetscObject)sp), PETSC_ERR_ARG_UNKNOWN_TYPE, "Unknown PetscSpace type: %s", name);
78: PetscTryTypeMethod(sp, destroy);
79: sp->ops->destroy = NULL;
81: sp->dim = PETSC_DETERMINE;
82: PetscCall((*r)(sp));
83: PetscCall(PetscObjectChangeTypeName((PetscObject)sp, name));
84: PetscFunctionReturn(PETSC_SUCCESS);
85: }
87: /*@
88: PetscSpaceGetType - Gets the `PetscSpaceType` (as a string) from the object.
90: Not Collective
92: Input Parameter:
93: . sp - The `PetscSpace`
95: Output Parameter:
96: . name - The `PetscSpace` type name
98: Level: intermediate
100: .seealso: `PetscSpaceType`, `PetscSpace`, `PetscSpaceSetType()`, `PetscSpaceCreate()`
101: @*/
102: PetscErrorCode PetscSpaceGetType(PetscSpace sp, PetscSpaceType *name)
103: {
104: PetscFunctionBegin;
106: PetscAssertPointer(name, 2);
107: if (!PetscSpaceRegisterAllCalled) PetscCall(PetscSpaceRegisterAll());
108: *name = ((PetscObject)sp)->type_name;
109: PetscFunctionReturn(PETSC_SUCCESS);
110: }
112: /*@
113: PetscSpaceViewFromOptions - View a `PetscSpace` based on values in the options database
115: Collective
117: Input Parameters:
118: + A - the `PetscSpace` object
119: . obj - Optional object that provides the options name prefix
120: - name - command line option name
122: Level: intermediate
124: .seealso: `PetscSpace`, `PetscSpaceView()`, `PetscObjectViewFromOptions()`, `PetscSpaceCreate()`
125: @*/
126: PetscErrorCode PetscSpaceViewFromOptions(PetscSpace A, PetscObject obj, const char name[])
127: {
128: PetscFunctionBegin;
130: PetscCall(PetscObjectViewFromOptions((PetscObject)A, obj, name));
131: PetscFunctionReturn(PETSC_SUCCESS);
132: }
134: /*@
135: PetscSpaceView - Views a `PetscSpace`
137: Collective
139: Input Parameters:
140: + sp - the `PetscSpace` object to view
141: - v - the viewer
143: Level: beginner
145: .seealso: `PetscSpace`, `PetscViewer`, `PetscSpaceViewFromOptions()`, `PetscSpaceDestroy()`
146: @*/
147: PetscErrorCode PetscSpaceView(PetscSpace sp, PetscViewer v)
148: {
149: PetscInt pdim;
150: PetscBool isascii;
152: PetscFunctionBegin;
155: if (!v) PetscCall(PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)sp), &v));
156: PetscCall(PetscSpaceGetDimension(sp, &pdim));
157: PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)sp, v));
158: PetscCall(PetscObjectTypeCompare((PetscObject)v, PETSCVIEWERASCII, &isascii));
159: PetscCall(PetscViewerASCIIPushTab(v));
160: if (isascii) PetscCall(PetscViewerASCIIPrintf(v, "Space in %" PetscInt_FMT " variables with %" PetscInt_FMT " components, size %" PetscInt_FMT "\n", sp->Nv, sp->Nc, pdim));
161: PetscTryTypeMethod(sp, view, v);
162: PetscCall(PetscViewerASCIIPopTab(v));
163: PetscFunctionReturn(PETSC_SUCCESS);
164: }
166: /*@
167: PetscSpaceSetFromOptions - sets parameters in a `PetscSpace` from the options database
169: Collective
171: Input Parameter:
172: . sp - the `PetscSpace` object to set options for
174: Options Database Keys:
175: + -petscspace_degree deg - the degree of the space
176: . -petscspace_variables n - the number of different variables, e.g. x and y
177: - -petscspace_components c - the number of components, say d for a vector field
179: Level: intermediate
181: .seealso: `PetscSpace`, `PetscSpaceView()`
182: @*/
183: PetscErrorCode PetscSpaceSetFromOptions(PetscSpace sp)
184: {
185: const char *defaultType;
186: char name[256];
187: PetscBool flg;
189: PetscFunctionBegin;
191: if (!((PetscObject)sp)->type_name) defaultType = PETSCSPACEPOLYNOMIAL;
192: else defaultType = ((PetscObject)sp)->type_name;
193: if (!PetscSpaceRegisterAllCalled) PetscCall(PetscSpaceRegisterAll());
195: PetscObjectOptionsBegin((PetscObject)sp);
196: PetscCall(PetscOptionsFList("-petscspace_type", "Linear space", "PetscSpaceSetType", PetscSpaceList, defaultType, name, 256, &flg));
197: if (flg) PetscCall(PetscSpaceSetType(sp, name));
198: else if (!((PetscObject)sp)->type_name) PetscCall(PetscSpaceSetType(sp, defaultType));
199: {
200: PetscCall(PetscOptionsDeprecated("-petscspace_order", "-petscspace_degree", "3.11", NULL));
201: }
202: PetscCall(PetscOptionsBoundedInt("-petscspace_degree", "The (maximally included) polynomial degree", "PetscSpaceSetDegree", sp->degree, &sp->degree, NULL, 0));
203: PetscCall(PetscOptionsBoundedInt("-petscspace_variables", "The number of different variables, e.g. x and y", "PetscSpaceSetNumVariables", sp->Nv, &sp->Nv, NULL, 0));
204: PetscCall(PetscOptionsBoundedInt("-petscspace_components", "The number of components", "PetscSpaceSetNumComponents", sp->Nc, &sp->Nc, NULL, -1));
205: PetscTryTypeMethod(sp, setfromoptions, PetscOptionsObject);
206: /* process any options handlers added with PetscObjectAddOptionsHandler() */
207: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)sp, PetscOptionsObject));
208: PetscOptionsEnd();
209: PetscCall(PetscSpaceViewFromOptions(sp, NULL, "-petscspace_view"));
210: PetscFunctionReturn(PETSC_SUCCESS);
211: }
213: /*@
214: PetscSpaceSetUp - Construct data structures for the `PetscSpace`
216: Collective
218: Input Parameter:
219: . sp - the `PetscSpace` object to setup
221: Level: intermediate
223: .seealso: `PetscSpace`, `PetscSpaceView()`, `PetscSpaceDestroy()`
224: @*/
225: PetscErrorCode PetscSpaceSetUp(PetscSpace sp)
226: {
227: PetscFunctionBegin;
229: PetscTryTypeMethod(sp, setup);
230: PetscFunctionReturn(PETSC_SUCCESS);
231: }
233: /*@
234: PetscSpaceDestroy - Destroys a `PetscSpace` object
236: Collective
238: Input Parameter:
239: . sp - the `PetscSpace` object to destroy
241: Level: beginner
243: .seealso: `PetscSpace`, `PetscSpaceCreate()`
244: @*/
245: PetscErrorCode PetscSpaceDestroy(PetscSpace *sp)
246: {
247: PetscFunctionBegin;
248: if (!*sp) PetscFunctionReturn(PETSC_SUCCESS);
251: if (--((PetscObject)*sp)->refct > 0) {
252: *sp = NULL;
253: PetscFunctionReturn(PETSC_SUCCESS);
254: }
255: ((PetscObject)*sp)->refct = 0;
256: PetscCall(DMDestroy(&(*sp)->dm));
258: PetscUseTypeMethod(*sp, destroy);
259: PetscCall(PetscHeaderDestroy(sp));
260: PetscFunctionReturn(PETSC_SUCCESS);
261: }
263: /*@
264: PetscSpaceCreate - Creates an empty `PetscSpace` object. The type can then be set with `PetscSpaceSetType()`.
266: Collective
268: Input Parameter:
269: . comm - The communicator for the `PetscSpace` object
271: Output Parameter:
272: . sp - The `PetscSpace` object
274: Level: beginner
276: .seealso: `PetscSpace`, `PetscSpaceSetType()`, `PETSCSPACEPOLYNOMIAL`
277: @*/
278: PetscErrorCode PetscSpaceCreate(MPI_Comm comm, PetscSpace *sp)
279: {
280: PetscSpace s;
282: PetscFunctionBegin;
283: PetscAssertPointer(sp, 2);
284: PetscCall(PetscCitationsRegister(FECitation, &FEcite));
285: PetscCall(PetscFEInitializePackage());
287: PetscCall(PetscHeaderCreate(s, PETSCSPACE_CLASSID, "PetscSpace", "Linear Space", "PetscSpace", comm, PetscSpaceDestroy, PetscSpaceView));
288: s->degree = 0;
289: s->maxDegree = PETSC_DETERMINE;
290: s->Nc = 1;
291: s->Nv = 0;
292: s->dim = PETSC_DETERMINE;
293: PetscCall(DMShellCreate(comm, &s->dm));
294: PetscCall(PetscSpaceSetType(s, PETSCSPACEPOLYNOMIAL));
296: *sp = s;
297: PetscFunctionReturn(PETSC_SUCCESS);
298: }
300: /*@
301: PetscSpaceGetDimension - Return the dimension of this space, i.e. the number of basis vectors
303: Input Parameter:
304: . sp - The `PetscSpace`
306: Output Parameter:
307: . dim - The dimension
309: Level: intermediate
311: .seealso: `PetscSpace`, `PetscSpaceGetDegree()`, `PetscSpaceCreate()`
312: @*/
313: PetscErrorCode PetscSpaceGetDimension(PetscSpace sp, PetscInt *dim)
314: {
315: PetscFunctionBegin;
317: PetscAssertPointer(dim, 2);
318: if (sp->dim == PETSC_DETERMINE) PetscTryTypeMethod(sp, getdimension, &sp->dim);
319: *dim = sp->dim;
320: PetscFunctionReturn(PETSC_SUCCESS);
321: }
323: /*@
324: PetscSpaceGetDegree - Return the polynomial degrees that characterize this space
326: Input Parameter:
327: . sp - The `PetscSpace`
329: Output Parameters:
330: + minDegree - The degree of the largest polynomial space contained in the space, pass `NULL` if not needed
331: - maxDegree - The degree of the smallest polynomial space containing the space, pass `NULL` if not needed
333: Level: intermediate
335: .seealso: `PetscSpace`, `PetscSpaceSetDegree()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
336: @*/
337: PetscErrorCode PetscSpaceGetDegree(PetscSpace sp, PeOp PetscInt *minDegree, PeOp PetscInt *maxDegree)
338: {
339: PetscFunctionBegin;
341: if (minDegree) PetscAssertPointer(minDegree, 2);
342: if (maxDegree) PetscAssertPointer(maxDegree, 3);
343: if (minDegree) *minDegree = sp->degree;
344: if (maxDegree) *maxDegree = sp->maxDegree;
345: PetscFunctionReturn(PETSC_SUCCESS);
346: }
348: /*@
349: PetscSpaceSetDegree - Set the degree of approximation for this space.
351: Input Parameters:
352: + sp - The `PetscSpace`
353: . degree - The degree of the largest polynomial space contained in the space
354: - maxDegree - The degree of the largest polynomial space containing the space. One of degree and maxDegree can be `PETSC_DETERMINE`.
356: Level: intermediate
358: .seealso: `PetscSpace`, `PetscSpaceGetDegree()`, `PetscSpaceCreate()`
359: @*/
360: PetscErrorCode PetscSpaceSetDegree(PetscSpace sp, PetscInt degree, PetscInt maxDegree)
361: {
362: PetscFunctionBegin;
364: sp->degree = degree;
365: sp->maxDegree = maxDegree;
366: PetscFunctionReturn(PETSC_SUCCESS);
367: }
369: /*@
370: PetscSpaceGetNumComponents - Return the number of components for this space
372: Input Parameter:
373: . sp - The `PetscSpace`
375: Output Parameter:
376: . Nc - The number of components
378: Level: intermediate
380: Note:
381: A vector space, for example, will have d components, where d is the spatial dimension
383: .seealso: `PetscSpace`, `PetscSpaceSetNumComponents()`, `PetscSpaceGetNumVariables()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
384: @*/
385: PetscErrorCode PetscSpaceGetNumComponents(PetscSpace sp, PetscInt *Nc)
386: {
387: PetscFunctionBegin;
389: PetscAssertPointer(Nc, 2);
390: *Nc = sp->Nc;
391: PetscFunctionReturn(PETSC_SUCCESS);
392: }
394: /*@
395: PetscSpaceSetNumComponents - Set the number of components for this space
397: Input Parameters:
398: + sp - The `PetscSpace`
399: - Nc - The number of components
401: Level: intermediate
403: .seealso: `PetscSpace`, `PetscSpaceGetNumComponents()`, `PetscSpaceSetNumVariables()`, `PetscSpaceCreate()`
404: @*/
405: PetscErrorCode PetscSpaceSetNumComponents(PetscSpace sp, PetscInt Nc)
406: {
407: PetscFunctionBegin;
409: sp->Nc = Nc;
410: PetscFunctionReturn(PETSC_SUCCESS);
411: }
413: /*@
414: PetscSpaceSetNumVariables - Set the number of variables for this space
416: Input Parameters:
417: + sp - The `PetscSpace`
418: - n - The number of variables, e.g. x, y, z...
420: Level: intermediate
422: .seealso: `PetscSpace`, `PetscSpaceGetNumVariables()`, `PetscSpaceSetNumComponents()`, `PetscSpaceCreate()`
423: @*/
424: PetscErrorCode PetscSpaceSetNumVariables(PetscSpace sp, PetscInt n)
425: {
426: PetscFunctionBegin;
428: sp->Nv = n;
429: PetscFunctionReturn(PETSC_SUCCESS);
430: }
432: /*@
433: PetscSpaceGetNumVariables - Return the number of variables for this space
435: Input Parameter:
436: . sp - The `PetscSpace`
438: Output Parameter:
439: . n - The number of variables, e.g. x, y, z...
441: Level: intermediate
443: .seealso: `PetscSpace`, `PetscSpaceSetNumVariables()`, `PetscSpaceGetNumComponents()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
444: @*/
445: PetscErrorCode PetscSpaceGetNumVariables(PetscSpace sp, PetscInt *n)
446: {
447: PetscFunctionBegin;
449: PetscAssertPointer(n, 2);
450: *n = sp->Nv;
451: PetscFunctionReturn(PETSC_SUCCESS);
452: }
454: /*@
455: PetscSpaceEvaluate - Evaluate the basis functions and their derivatives (jet) at each point
457: Input Parameters:
458: + sp - The `PetscSpace`
459: . npoints - The number of evaluation points, in reference coordinates
460: - points - The point coordinates
462: Output Parameters:
463: + B - The function evaluations in a `npoints` x `nfuncs` array
464: . D - The derivative evaluations in a `npoints` x `nfuncs` x `dim` array
465: - H - The second derivative evaluations in a `npoints` x `nfuncs` x `dim` x `dim` array
467: Level: beginner
469: Note:
470: Above `nfuncs` is the dimension of the space, and `dim` is the spatial dimension. The coordinates are given
471: on the reference cell, not in real space.
473: .seealso: `PetscSpace`, `PetscFECreateTabulation()`, `PetscFEGetCellTabulation()`, `PetscSpaceCreate()`
474: @*/
475: PetscErrorCode PetscSpaceEvaluate(PetscSpace sp, PetscInt npoints, const PetscReal points[], PeOp PetscReal B[], PeOp PetscReal D[], PeOp PetscReal H[])
476: {
477: PetscFunctionBegin;
478: if (!npoints) PetscFunctionReturn(PETSC_SUCCESS);
480: if (sp->Nv) PetscAssertPointer(points, 3);
481: if (B) PetscAssertPointer(B, 4);
482: if (D) PetscAssertPointer(D, 5);
483: if (H) PetscAssertPointer(H, 6);
484: PetscTryTypeMethod(sp, evaluate, npoints, points, B, D, H);
485: PetscFunctionReturn(PETSC_SUCCESS);
486: }
488: /*@
489: PetscSpaceGetHeightSubspace - Get the subset of the primal space basis that is supported on a mesh point of a given height.
491: Not Collective
493: Input Parameters:
494: + sp - the `PetscSpace` object
495: - height - the height of the mesh point for which the subspace is desired
497: Output Parameter:
498: . subsp - the subspace
500: Level: advanced
502: Notes:
503: If the space is not defined on mesh points of the given height (e.g. if the space is discontinuous and
504: pointwise values are not defined on the element boundaries), or if the implementation of `PetscSpace` does not
505: support extracting subspaces, then NULL is returned.
507: This does not increment the reference count on the returned space, and the user should not destroy it.
509: .seealso: `PetscDualSpaceGetHeightSubspace()`, `PetscSpace`
510: @*/
511: PetscErrorCode PetscSpaceGetHeightSubspace(PetscSpace sp, PetscInt height, PetscSpace *subsp)
512: {
513: PetscFunctionBegin;
515: PetscAssertPointer(subsp, 3);
516: *subsp = NULL;
517: PetscTryTypeMethod(sp, getheightsubspace, height, subsp);
518: PetscFunctionReturn(PETSC_SUCCESS);
519: }