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

 14:   Input Parameters:
 15: + name        - The name of a new user-defined creation routine
 16: - create_func - The creation routine for the implementation type

 18:   Notes:
 19:   PetscSpaceRegister() may be called multiple times to add several user-defined types of PetscSpaces.  The creation function is called
 20:   when the type is set to 'name'.

 22:   Sample usage:
 23: .vb
 24:     PetscSpaceRegister("my_space", MyPetscSpaceCreate);
 25: .ve

 27:   Then, your PetscSpace type can be chosen with the procedural interface via
 28: .vb
 29:     PetscSpaceCreate(MPI_Comm, PetscSpace *);
 30:     PetscSpaceSetType(PetscSpace, "my_space");
 31: .ve
 32:    or at runtime via the option
 33: .vb
 34:     -petscspace_type my_space
 35: .ve

 37:   Level: advanced

 39: .seealso: PetscSpaceRegisterAll(), PetscSpaceRegisterDestroy()

 41: @*/
 42: PetscErrorCode PetscSpaceRegister(const char sname[], PetscErrorCode (*function)(PetscSpace))
 43: {
 44:   PetscFunctionListAdd(&PetscSpaceList, sname, function);
 45:   return 0;
 46: }

 48: /*@C
 49:   PetscSpaceSetType - Builds a particular PetscSpace

 51:   Collective on sp

 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: PetscSpaceGetType(), PetscSpaceCreate()
 63: @*/
 64: PetscErrorCode PetscSpaceSetType(PetscSpace sp, PetscSpaceType name)
 65: {
 66:   PetscErrorCode (*r)(PetscSpace);
 67:   PetscBool      match;

 70:   PetscObjectTypeCompare((PetscObject) sp, name, &match);
 71:   if (match) return 0;

 73:   PetscSpaceRegisterAll();
 74:   PetscFunctionListFind(PetscSpaceList, name, &r);

 77:   if (sp->ops->destroy) {
 78:     (*sp->ops->destroy)(sp);
 79:     sp->ops->destroy = NULL;
 80:   }
 81:   sp->dim = PETSC_DETERMINE;
 82:   (*r)(sp);
 83:   PetscObjectChangeTypeName((PetscObject) sp, name);
 84:   return 0;
 85: }

 87: /*@C
 88:   PetscSpaceGetType - Gets the PetscSpace type name (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: PetscSpaceSetType(), PetscSpaceCreate()
101: @*/
102: PetscErrorCode PetscSpaceGetType(PetscSpace sp, PetscSpaceType *name)
103: {
106:   if (!PetscSpaceRegisterAllCalled) {
107:     PetscSpaceRegisterAll();
108:   }
109:   *name = ((PetscObject) sp)->type_name;
110:   return 0;
111: }

113: /*@C
114:    PetscSpaceViewFromOptions - View from Options

116:    Collective on PetscSpace

118:    Input Parameters:
119: +  A - the PetscSpace object
120: .  obj - Optional object
121: -  name - command line option

123:    Level: intermediate
124: .seealso:  PetscSpace, PetscSpaceView, PetscObjectViewFromOptions(), PetscSpaceCreate()
125: @*/
126: PetscErrorCode  PetscSpaceViewFromOptions(PetscSpace A,PetscObject obj,const char name[])
127: {
129:   PetscObjectViewFromOptions((PetscObject)A,obj,name);
130:   return 0;
131: }

133: /*@C
134:   PetscSpaceView - Views a PetscSpace

136:   Collective on sp

138:   Input Parameters:
139: + sp - the PetscSpace object to view
140: - v  - the viewer

142:   Level: beginner

144: .seealso PetscSpaceDestroy()
145: @*/
146: PetscErrorCode PetscSpaceView(PetscSpace sp, PetscViewer v)
147: {
148:   PetscInt       pdim;
149:   PetscBool      iascii;

153:   if (!v) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject) sp), &v);
154:   PetscSpaceGetDimension(sp, &pdim);
155:   PetscObjectPrintClassNamePrefixType((PetscObject)sp,v);
156:   PetscObjectTypeCompare((PetscObject) v, PETSCVIEWERASCII, &iascii);
157:   PetscViewerASCIIPushTab(v);
158:   if (iascii) PetscViewerASCIIPrintf(v, "Space in %D variables with %D components, size %D\n", sp->Nv, sp->Nc, pdim);
159:   if (sp->ops->view) (*sp->ops->view)(sp, v);
160:   PetscViewerASCIIPopTab(v);
161:   return 0;
162: }

164: /*@
165:   PetscSpaceSetFromOptions - sets parameters in a PetscSpace from the options database

167:   Collective on sp

169:   Input Parameter:
170: . sp - the PetscSpace object to set options for

172:   Options Database:
173: + -petscspace_degree <deg> - the approximation order of the space
174: . -petscspace_variables <n> - the number of different variables, e.g. x and y
175: - -petscspace_components <c> - the number of components, say d for a vector field

177:   Level: intermediate

179: .seealso PetscSpaceView()
180: @*/
181: PetscErrorCode PetscSpaceSetFromOptions(PetscSpace sp)
182: {
183:   const char    *defaultType;
184:   char           name[256];
185:   PetscBool      flg;

189:   if (!((PetscObject) sp)->type_name) {
190:     defaultType = PETSCSPACEPOLYNOMIAL;
191:   } else {
192:     defaultType = ((PetscObject) sp)->type_name;
193:   }
194:   if (!PetscSpaceRegisterAllCalled) PetscSpaceRegisterAll();

196:   PetscObjectOptionsBegin((PetscObject) sp);
197:   PetscOptionsFList("-petscspace_type", "Linear space", "PetscSpaceSetType", PetscSpaceList, defaultType, name, 256, &flg);
198:   if (flg) {
199:     PetscSpaceSetType(sp, name);
200:   } else if (!((PetscObject) sp)->type_name) {
201:     PetscSpaceSetType(sp, defaultType);
202:   }
203:   {
204:     PetscOptionsDeprecated("-petscspace_order","-petscspace_degree","3.11",NULL);
205:     PetscOptionsBoundedInt("-petscspace_order", "DEPRECATED: The approximation order", "PetscSpaceSetDegree", sp->degree, &sp->degree, NULL,0);
206:   }
207:   PetscOptionsBoundedInt("-petscspace_degree", "The (maximally included) polynomial degree", "PetscSpaceSetDegree", sp->degree, &sp->degree, NULL,0);
208:   PetscOptionsBoundedInt("-petscspace_variables", "The number of different variables, e.g. x and y", "PetscSpaceSetNumVariables", sp->Nv, &sp->Nv, NULL,0);
209:   PetscOptionsBoundedInt("-petscspace_components", "The number of components", "PetscSpaceSetNumComponents", sp->Nc, &sp->Nc, NULL,0);
210:   if (sp->ops->setfromoptions) {
211:     (*sp->ops->setfromoptions)(PetscOptionsObject,sp);
212:   }
213:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
214:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject) sp);
215:   PetscOptionsEnd();
216:   PetscSpaceViewFromOptions(sp, NULL, "-petscspace_view");
217:   return 0;
218: }

220: /*@C
221:   PetscSpaceSetUp - Construct data structures for the PetscSpace

223:   Collective on sp

225:   Input Parameter:
226: . sp - the PetscSpace object to setup

228:   Level: intermediate

230: .seealso PetscSpaceView(), PetscSpaceDestroy()
231: @*/
232: PetscErrorCode PetscSpaceSetUp(PetscSpace sp)
233: {
235:   if (sp->ops->setup) (*sp->ops->setup)(sp);
236:   return 0;
237: }

239: /*@
240:   PetscSpaceDestroy - Destroys a PetscSpace object

242:   Collective on sp

244:   Input Parameter:
245: . sp - the PetscSpace object to destroy

247:   Level: beginner

249: .seealso PetscSpaceView()
250: @*/
251: PetscErrorCode PetscSpaceDestroy(PetscSpace *sp)
252: {
253:   if (!*sp) return 0;

256:   if (--((PetscObject)(*sp))->refct > 0) {*sp = NULL; return 0;}
257:   ((PetscObject) (*sp))->refct = 0;
258:   DMDestroy(&(*sp)->dm);

260:   (*(*sp)->ops->destroy)(*sp);
261:   PetscHeaderDestroy(sp);
262:   return 0;
263: }

265: /*@
266:   PetscSpaceCreate - Creates an empty PetscSpace object. The type can then be set with PetscSpaceSetType().

268:   Collective

270:   Input Parameter:
271: . comm - The communicator for the PetscSpace object

273:   Output Parameter:
274: . sp - The PetscSpace object

276:   Level: beginner

278: .seealso: PetscSpaceSetType(), PETSCSPACEPOLYNOMIAL
279: @*/
280: PetscErrorCode PetscSpaceCreate(MPI_Comm comm, PetscSpace *sp)
281: {
282:   PetscSpace     s;

285:   PetscCitationsRegister(FECitation,&FEcite);
286:   *sp  = NULL;
287:   PetscFEInitializePackage();

289:   PetscHeaderCreate(s, PETSCSPACE_CLASSID, "PetscSpace", "Linear Space", "PetscSpace", comm, PetscSpaceDestroy, PetscSpaceView);

291:   s->degree    = 0;
292:   s->maxDegree = PETSC_DETERMINE;
293:   s->Nc        = 1;
294:   s->Nv        = 0;
295:   s->dim       = PETSC_DETERMINE;
296:   DMShellCreate(comm, &s->dm);
297:   PetscSpaceSetType(s, PETSCSPACEPOLYNOMIAL);

299:   *sp = s;
300:   return 0;
301: }

303: /*@
304:   PetscSpaceGetDimension - Return the dimension of this space, i.e. the number of basis vectors

306:   Input Parameter:
307: . sp - The PetscSpace

309:   Output Parameter:
310: . dim - The dimension

312:   Level: intermediate

314: .seealso: PetscSpaceGetDegree(), PetscSpaceCreate(), PetscSpace
315: @*/
316: PetscErrorCode PetscSpaceGetDimension(PetscSpace sp, PetscInt *dim)
317: {
320:   if (sp->dim == PETSC_DETERMINE) {
321:     if (sp->ops->getdimension) (*sp->ops->getdimension)(sp, &sp->dim);
322:   }
323:   *dim = sp->dim;
324:   return 0;
325: }

327: /*@
328:   PetscSpaceGetDegree - Return the polynomial degrees that characterize this space

330:   Input Parameter:
331: . sp - The PetscSpace

333:   Output Parameters:
334: + minDegree - The degree of the largest polynomial space contained in the space
335: - maxDegree - The degree of the smallest polynomial space containing the space

337:   Level: intermediate

339: .seealso: PetscSpaceSetDegree(), PetscSpaceGetDimension(), PetscSpaceCreate(), PetscSpace
340: @*/
341: PetscErrorCode PetscSpaceGetDegree(PetscSpace sp, PetscInt *minDegree, PetscInt *maxDegree)
342: {
346:   if (minDegree) *minDegree = sp->degree;
347:   if (maxDegree) *maxDegree = sp->maxDegree;
348:   return 0;
349: }

351: /*@
352:   PetscSpaceSetDegree - Set the degree of approximation for this space.

354:   Input Parameters:
355: + sp - The PetscSpace
356: . degree - The degree of the largest polynomial space contained in the space
357: - maxDegree - The degree of the largest polynomial space containing the space.  One of degree and maxDegree can be PETSC_DETERMINE.

359:   Level: intermediate

361: .seealso: PetscSpaceGetDegree(), PetscSpaceCreate(), PetscSpace
362: @*/
363: PetscErrorCode PetscSpaceSetDegree(PetscSpace sp, PetscInt degree, PetscInt maxDegree)
364: {
366:   sp->degree = degree;
367:   sp->maxDegree = maxDegree;
368:   return 0;
369: }

371: /*@
372:   PetscSpaceGetNumComponents - Return the number of components for this space

374:   Input Parameter:
375: . sp - The PetscSpace

377:   Output Parameter:
378: . Nc - The number of components

380:   Note: A vector space, for example, will have d components, where d is the spatial dimension

382:   Level: intermediate

384: .seealso: PetscSpaceSetNumComponents(), PetscSpaceGetNumVariables(), PetscSpaceGetDimension(), PetscSpaceCreate(), PetscSpace
385: @*/
386: PetscErrorCode PetscSpaceGetNumComponents(PetscSpace sp, PetscInt *Nc)
387: {
390:   *Nc = sp->Nc;
391:   return 0;
392: }

394: /*@
395:   PetscSpaceSetNumComponents - Set the number of components for this space

397:   Input Parameters:
398: + sp - The PetscSpace
399: - order - The number of components

401:   Level: intermediate

403: .seealso: PetscSpaceGetNumComponents(), PetscSpaceSetNumVariables(), PetscSpaceCreate(), PetscSpace
404: @*/
405: PetscErrorCode PetscSpaceSetNumComponents(PetscSpace sp, PetscInt Nc)
406: {
408:   sp->Nc = Nc;
409:   return 0;
410: }

412: /*@
413:   PetscSpaceSetNumVariables - Set the number of variables for this space

415:   Input Parameters:
416: + sp - The PetscSpace
417: - n - The number of variables, e.g. x, y, z...

419:   Level: intermediate

421: .seealso: PetscSpaceGetNumVariables(), PetscSpaceSetNumComponents(), PetscSpaceCreate(), PetscSpace
422: @*/
423: PetscErrorCode PetscSpaceSetNumVariables(PetscSpace sp, PetscInt n)
424: {
426:   sp->Nv = n;
427:   return 0;
428: }

430: /*@
431:   PetscSpaceGetNumVariables - Return the number of variables for this space

433:   Input Parameter:
434: . sp - The PetscSpace

436:   Output Parameter:
437: . Nc - The number of variables, e.g. x, y, z...

439:   Level: intermediate

441: .seealso: PetscSpaceSetNumVariables(), PetscSpaceGetNumComponents(), PetscSpaceGetDimension(), PetscSpaceCreate(), PetscSpace
442: @*/
443: PetscErrorCode PetscSpaceGetNumVariables(PetscSpace sp, PetscInt *n)
444: {
447:   *n = sp->Nv;
448:   return 0;
449: }

451: /*@C
452:   PetscSpaceEvaluate - Evaluate the basis functions and their derivatives (jet) at each point

454:   Input Parameters:
455: + sp      - The PetscSpace
456: . npoints - The number of evaluation points, in reference coordinates
457: - points  - The point coordinates

459:   Output Parameters:
460: + B - The function evaluations in a npoints x nfuncs array
461: . D - The derivative evaluations in a npoints x nfuncs x dim array
462: - H - The second derivative evaluations in a npoints x nfuncs x dim x dim array

464:   Note: Above nfuncs is the dimension of the space, and dim is the spatial dimension. The coordinates are given
465:   on the reference cell, not in real space.

467:   Level: beginner

469: .seealso: PetscFECreateTabulation(), PetscFEGetCellTabulation(), PetscSpaceCreate()
470: @*/
471: PetscErrorCode PetscSpaceEvaluate(PetscSpace sp, PetscInt npoints, const PetscReal points[], PetscReal B[], PetscReal D[], PetscReal H[])
472: {
473:   if (!npoints) return 0;
479:   if (sp->ops->evaluate) (*sp->ops->evaluate)(sp, npoints, points, B, D, H);
480:   return 0;
481: }

483: /*@
484:   PetscSpaceGetHeightSubspace - Get the subset of the primal space basis that is supported on a mesh point of a given height.

486:   If the space is not defined on mesh points of the given height (e.g. if the space is discontinuous and
487:   pointwise values are not defined on the element boundaries), or if the implementation of PetscSpace does not
488:   support extracting subspaces, then NULL is returned.

490:   This does not increment the reference count on the returned space, and the user should not destroy it.

492:   Not collective

494:   Input Parameters:
495: + sp - the PetscSpace object
496: - height - the height of the mesh point for which the subspace is desired

498:   Output Parameter:
499: . subsp - the subspace

501:   Level: advanced

503: .seealso: PetscDualSpaceGetHeightSubspace(), PetscSpace
504: @*/
505: PetscErrorCode PetscSpaceGetHeightSubspace(PetscSpace sp, PetscInt height, PetscSpace *subsp)
506: {
509:   *subsp = NULL;
510:   if (sp->ops->getheightsubspace) {
511:     (*sp->ops->getheightsubspace)(sp, height, subsp);
512:   }
513:   return 0;
514: }