Actual source code: space.c

petsc-master 2019-06-26
Report Typos and Errors
  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: {

 47:   PetscFunctionListAdd(&PetscSpaceList, sname, function);
 48:   return(0);
 49: }

 51: /*@C
 52:   PetscSpaceSetType - Builds a particular PetscSpace

 54:   Collective on sp

 56:   Input Parameters:
 57: + sp   - The PetscSpace object
 58: - name - The kind of space

 60:   Options Database Key:
 61: . -petscspace_type <type> - Sets the PetscSpace type; use -help for a list of available types

 63:   Level: intermediate

 65: .seealso: PetscSpaceGetType(), PetscSpaceCreate()
 66: @*/
 67: PetscErrorCode PetscSpaceSetType(PetscSpace sp, PetscSpaceType name)
 68: {
 69:   PetscErrorCode (*r)(PetscSpace);
 70:   PetscBool      match;

 75:   PetscObjectTypeCompare((PetscObject) sp, name, &match);
 76:   if (match) return(0);

 78:   PetscSpaceRegisterAll();
 79:   PetscFunctionListFind(PetscSpaceList, name, &r);
 80:   if (!r) SETERRQ1(PetscObjectComm((PetscObject) sp), PETSC_ERR_ARG_UNKNOWN_TYPE, "Unknown PetscSpace type: %s", name);

 82:   if (sp->ops->destroy) {
 83:     (*sp->ops->destroy)(sp);
 84:     sp->ops->destroy = NULL;
 85:   }
 86:   sp->dim = PETSC_DETERMINE;
 87:   (*r)(sp);
 88:   PetscObjectChangeTypeName((PetscObject) sp, name);
 89:   return(0);
 90: }

 92: /*@C
 93:   PetscSpaceGetType - Gets the PetscSpace type name (as a string) from the object.

 95:   Not Collective

 97:   Input Parameter:
 98: . sp  - The PetscSpace

100:   Output Parameter:
101: . name - The PetscSpace type name

103:   Level: intermediate

105: .seealso: PetscSpaceSetType(), PetscSpaceCreate()
106: @*/
107: PetscErrorCode PetscSpaceGetType(PetscSpace sp, PetscSpaceType *name)
108: {

114:   if (!PetscSpaceRegisterAllCalled) {
115:     PetscSpaceRegisterAll();
116:   }
117:   *name = ((PetscObject) sp)->type_name;
118:   return(0);
119: }

121: /*@C
122:   PetscSpaceView - Views a PetscSpace

124:   Collective on sp

126:   Input Parameter:
127: + sp - the PetscSpace object to view
128: - v  - the viewer

130:   Level: developer

132: .seealso PetscSpaceDestroy()
133: @*/
134: PetscErrorCode PetscSpaceView(PetscSpace sp, PetscViewer v)
135: {
136:   PetscInt       pdim;
137:   PetscBool      iascii;

143:   if (!v) {PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject) sp), &v);}
144:   PetscSpaceGetDimension(sp, &pdim);
145:   PetscObjectPrintClassNamePrefixType((PetscObject)sp,v);
146:   PetscObjectTypeCompare((PetscObject) v, PETSCVIEWERASCII, &iascii);
147:   PetscViewerASCIIPushTab(v);
148:   if (iascii) {PetscViewerASCIIPrintf(v, "Space in %D variables with %D components, size %D\n", sp->Nv, sp->Nc, pdim);}
149:   if (sp->ops->view) {(*sp->ops->view)(sp, v);}
150:   PetscViewerASCIIPopTab(v);
151:   return(0);
152: }

154: /*@
155:   PetscSpaceSetFromOptions - sets parameters in a PetscSpace from the options database

157:   Collective on sp

159:   Input Parameter:
160: . sp - the PetscSpace object to set options for

162:   Options Database:
163: . -petscspace_degree the approximation order of the space

165:   Level: developer

167: .seealso PetscSpaceView()
168: @*/
169: PetscErrorCode PetscSpaceSetFromOptions(PetscSpace sp)
170: {
171:   const char    *defaultType;
172:   char           name[256];
173:   PetscBool      flg, orderflg;

178:   if (!((PetscObject) sp)->type_name) {
179:     defaultType = PETSCSPACEPOLYNOMIAL;
180:   } else {
181:     defaultType = ((PetscObject) sp)->type_name;
182:   }
183:   if (!PetscSpaceRegisterAllCalled) {PetscSpaceRegisterAll();}

185:   PetscObjectOptionsBegin((PetscObject) sp);
186:   PetscOptionsFList("-petscspace_type", "Linear space", "PetscSpaceSetType", PetscSpaceList, defaultType, name, 256, &flg);
187:   if (flg) {
188:     PetscSpaceSetType(sp, name);
189:   } else if (!((PetscObject) sp)->type_name) {
190:     PetscSpaceSetType(sp, defaultType);
191:   }
192:   {
193:     PetscOptionsInt("-petscspace_order", "DEPRECATED: The approximation order", "PetscSpaceSetDegree", sp->degree, &sp->degree, &orderflg);
194:     if (orderflg) {
195:       int compare;

197:       MPI_Comm_compare(PetscObjectComm((PetscObject)sp), PETSC_COMM_WORLD, &compare);

199:       if (compare == MPI_IDENT || compare == MPI_CONGRUENT) {
200:         PetscPrintf(PetscObjectComm((PetscObject)sp), "Warning: -petscspace_order is deprecated.  Use -petscspace_degree\n");
201:       }
202:     }
203:   }
204:   PetscOptionsInt("-petscspace_degree", "The (maximally included) polynomial degree", "PetscSpaceSetDegree", sp->degree, &sp->degree, NULL);
205:   PetscOptionsInt("-petscspace_variables", "The number of different variables, e.g. x and y", "PetscSpaceSetNumVariables", sp->Nv, &sp->Nv, NULL);
206:   PetscOptionsInt("-petscspace_components", "The number of components", "PetscSpaceSetNumComponents", sp->Nc, &sp->Nc, NULL);
207:   if (sp->ops->setfromoptions) {
208:     (*sp->ops->setfromoptions)(PetscOptionsObject,sp);
209:   }
210:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
211:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject) sp);
212:   PetscOptionsEnd();
213:   PetscSpaceViewFromOptions(sp, NULL, "-petscspace_view");
214:   return(0);
215: }

217: /*@C
218:   PetscSpaceSetUp - Construct data structures for the PetscSpace

220:   Collective on sp

222:   Input Parameter:
223: . sp - the PetscSpace object to setup

225:   Level: developer

227: .seealso PetscSpaceView(), PetscSpaceDestroy()
228: @*/
229: PetscErrorCode PetscSpaceSetUp(PetscSpace sp)
230: {

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

249: .seealso PetscSpaceView()
250: @*/
251: PetscErrorCode PetscSpaceDestroy(PetscSpace *sp)
252: {

256:   if (!*sp) return(0);

259:   if (--((PetscObject)(*sp))->refct > 0) {*sp = 0; return(0);}
260:   ((PetscObject) (*sp))->refct = 0;
261:   DMDestroy(&(*sp)->dm);

263:   (*(*sp)->ops->destroy)(*sp);
264:   PetscHeaderDestroy(sp);
265:   return(0);
266: }

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

271:   Collective

273:   Input Parameter:
274: . comm - The communicator for the PetscSpace object

276:   Output Parameter:
277: . sp - The PetscSpace object

279:   Level: beginner

281: .seealso: PetscSpaceSetType(), PETSCSPACEPOLYNOMIAL
282: @*/
283: PetscErrorCode PetscSpaceCreate(MPI_Comm comm, PetscSpace *sp)
284: {
285:   PetscSpace     s;

290:   PetscCitationsRegister(FECitation,&FEcite);
291:   *sp  = NULL;
292:   PetscFEInitializePackage();

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

296:   s->degree    = 0;
297:   s->maxDegree = PETSC_DETERMINE;
298:   s->Nc        = 1;
299:   s->Nv        = 0;
300:   s->dim       = PETSC_DETERMINE;
301:   DMShellCreate(comm, &s->dm);
302:   PetscSpaceSetType(s, PETSCSPACEPOLYNOMIAL);

304:   *sp = s;
305:   return(0);
306: }

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

311:   Input Parameter:
312: . sp - The PetscSpace

314:   Output Parameter:
315: . dim - The dimension

317:   Level: intermediate

319: .seealso: PetscSpaceGetDegree(), PetscSpaceCreate(), PetscSpace
320: @*/
321: PetscErrorCode PetscSpaceGetDimension(PetscSpace sp, PetscInt *dim)
322: {

328:   if (sp->dim == PETSC_DETERMINE) {
329:     if (sp->ops->getdimension) {(*sp->ops->getdimension)(sp, &sp->dim);}
330:   }
331:   *dim = sp->dim;
332:   return(0);
333: }

335: /*@
336:   PetscSpaceGetDegree - Return the polynomial degrees that characterize this space

338:   Input Parameter:
339: . sp - The PetscSpace

341:   Output Parameter:
342: + minDegree - The degree of the largest polynomial space contained in the space
343: - maxDegree - The degree of the smallest polynomial space containing the space


346:   Level: intermediate

348: .seealso: PetscSpaceSetDegree(), PetscSpaceGetDimension(), PetscSpaceCreate(), PetscSpace
349: @*/
350: PetscErrorCode PetscSpaceGetDegree(PetscSpace sp, PetscInt *minDegree, PetscInt *maxDegree)
351: {
356:   if (minDegree) *minDegree = sp->degree;
357:   if (maxDegree) *maxDegree = sp->maxDegree;
358:   return(0);
359: }

361: /*@
362:   PetscSpaceSetDegree - Set the degree of approximation for this space.

364:   Input Parameters:
365: + sp - The PetscSpace
366: . degree - The degree of the largest polynomial space contained in the space
367: - maxDegree - The degree of the largest polynomial space containing the space.  One of degree and maxDegree can be PETSC_DETERMINE.

369:   Level: intermediate

371: .seealso: PetscSpaceGetDegree(), PetscSpaceCreate(), PetscSpace
372: @*/
373: PetscErrorCode PetscSpaceSetDegree(PetscSpace sp, PetscInt degree, PetscInt maxDegree)
374: {
377:   sp->degree = degree;
378:   sp->maxDegree = maxDegree;
379:   return(0);
380: }

382: /*@
383:   PetscSpaceGetNumComponents - Return the number of components for this space

385:   Input Parameter:
386: . sp - The PetscSpace

388:   Output Parameter:
389: . Nc - The number of components

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

393:   Level: intermediate

395: .seealso: PetscSpaceSetNumComponents(), PetscSpaceGetDimension(), PetscSpaceCreate(), PetscSpace
396: @*/
397: PetscErrorCode PetscSpaceGetNumComponents(PetscSpace sp, PetscInt *Nc)
398: {
402:   *Nc = sp->Nc;
403:   return(0);
404: }

406: /*@
407:   PetscSpaceSetNumComponents - Set the number of components for this space

409:   Input Parameters:
410: + sp - The PetscSpace
411: - order - The number of components

413:   Level: intermediate

415: .seealso: PetscSpaceGetNumComponents(), PetscSpaceCreate(), PetscSpace
416: @*/
417: PetscErrorCode PetscSpaceSetNumComponents(PetscSpace sp, PetscInt Nc)
418: {
421:   sp->Nc = Nc;
422:   return(0);
423: }

425: PetscErrorCode PetscSpaceSetNumVariables(PetscSpace sp, PetscInt n)
426: {
429:   sp->Nv = n;
430:   return(0);
431: }

433: PetscErrorCode PetscSpaceGetNumVariables(PetscSpace sp, PetscInt *n)
434: {
438:   *n = sp->Nv;
439:   return(0);
440: }


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

446:   Input Parameters:
447: + sp      - The PetscSpace
448: . npoints - The number of evaluation points, in reference coordinates
449: - points  - The point coordinates

451:   Output Parameters:
452: + B - The function evaluations in a npoints x nfuncs array
453: . D - The derivative evaluations in a npoints x nfuncs x dim array
454: - H - The second derivative evaluations in a npoints x nfuncs x dim x dim array

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

459:   Level: advanced

461: .seealso: PetscFEGetTabulation(), PetscFEGetDefaultTabulation(), PetscSpaceCreate()
462: @*/
463: PetscErrorCode PetscSpaceEvaluate(PetscSpace sp, PetscInt npoints, const PetscReal points[], PetscReal B[], PetscReal D[], PetscReal H[])
464: {

468:   if (!npoints) return(0);
474:   if (sp->ops->evaluate) {(*sp->ops->evaluate)(sp, npoints, points, B, D, H);}
475:   return(0);
476: }

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

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

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

487:   Not collective

489:   Input Parameters:
490: + sp - the PetscSpace object
491: - height - the height of the mesh point for which the subspace is desired

493:   Output Parameter:
494: . subsp - the subspace

496:   Level: advanced

498: .seealso: PetscDualSpaceGetHeightSubspace(), PetscSpace
499: @*/
500: PetscErrorCode PetscSpaceGetHeightSubspace(PetscSpace sp, PetscInt height, PetscSpace *subsp)
501: {

507:   *subsp = NULL;
508:   if (sp->ops->getheightsubspace) {
509:     (*sp->ops->getheightsubspace)(sp, height, subsp);
510:   }
511:   return(0);
512: }