Date: 2026-03-01T05:24:35+00:00

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 approximation order 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) {
    192:     defaultType = PETSCSPACEPOLYNOMIAL;
    193:   } else {
    194:     defaultType = ((PetscObject)sp)->type_name;
    195:   }
    196:   if (!PetscSpaceRegisterAllCalled) PetscCall(PetscSpaceRegisterAll());

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

    219: /*@
    220:   PetscSpaceSetUp - Construct data structures for the `PetscSpace`

    222:   Collective

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

    227:   Level: intermediate

    229: .seealso: `PetscSpace`, `PetscSpaceView()`, `PetscSpaceDestroy()`
    230: @*/
    231: PetscErrorCode PetscSpaceSetUp(PetscSpace sp)
    232: {
    233:   PetscFunctionBegin;
    235:   PetscTryTypeMethod(sp, setup);
    236:   PetscFunctionReturn(PETSC_SUCCESS);
    237: }

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

    242:   Collective

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

    247:   Level: beginner

    249: .seealso: `PetscSpace`, `PetscSpaceCreate()`
    250: @*/
    251: PetscErrorCode PetscSpaceDestroy(PetscSpace *sp)
    252: {
    253:   PetscFunctionBegin;
    254:   if (!*sp) PetscFunctionReturn(PETSC_SUCCESS);

    257:   if (--((PetscObject)*sp)->refct > 0) {
    258:     *sp = NULL;
    259:     PetscFunctionReturn(PETSC_SUCCESS);
    260:   }
    261:   ((PetscObject)*sp)->refct = 0;
    262:   PetscCall(DMDestroy(&(*sp)->dm));

    264:   PetscUseTypeMethod(*sp, destroy);
    265:   PetscCall(PetscHeaderDestroy(sp));
    266:   PetscFunctionReturn(PETSC_SUCCESS);
    267: }

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

    272:   Collective

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

    277:   Output Parameter:
    278: . sp - The `PetscSpace` object

    280:   Level: beginner

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

    288:   PetscFunctionBegin;
    289:   PetscAssertPointer(sp, 2);
    290:   PetscCall(PetscCitationsRegister(FECitation, &FEcite));
    291:   PetscCall(PetscFEInitializePackage());

    293:   PetscCall(PetscHeaderCreate(s, PETSCSPACE_CLASSID, "PetscSpace", "Linear Space", "PetscSpace", comm, PetscSpaceDestroy, PetscSpaceView));
    294:   s->degree    = 0;
    295:   s->maxDegree = PETSC_DETERMINE;
    296:   s->Nc        = 1;
    297:   s->Nv        = 0;
    298:   s->dim       = PETSC_DETERMINE;
    299:   PetscCall(DMShellCreate(comm, &s->dm));
    300:   PetscCall(PetscSpaceSetType(s, PETSCSPACEPOLYNOMIAL));

    302:   *sp = s;
    303:   PetscFunctionReturn(PETSC_SUCCESS);
    304: }

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

    309:   Input Parameter:
    310: . sp - The `PetscSpace`

    312:   Output Parameter:
    313: . dim - The dimension

    315:   Level: intermediate

    317: .seealso: `PetscSpace`, `PetscSpaceGetDegree()`, `PetscSpaceCreate()`
    318: @*/
    319: PetscErrorCode PetscSpaceGetDimension(PetscSpace sp, PetscInt *dim)
    320: {
    321:   PetscFunctionBegin;
    323:   PetscAssertPointer(dim, 2);
    324:   if (sp->dim == PETSC_DETERMINE) PetscTryTypeMethod(sp, getdimension, &sp->dim);
    325:   *dim = sp->dim;
    326:   PetscFunctionReturn(PETSC_SUCCESS);
    327: }

    329: /*@
    330:   PetscSpaceGetDegree - Return the polynomial degrees that characterize this space

    332:   Input Parameter:
    333: . sp - The `PetscSpace`

    335:   Output Parameters:
    336: + minDegree - The degree of the largest polynomial space contained in the space, pass `NULL` if not needed
    337: - maxDegree - The degree of the smallest polynomial space containing the space, pass `NULL` if not needed

    339:   Level: intermediate

    341: .seealso: `PetscSpace`, `PetscSpaceSetDegree()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
    342: @*/
    343: PetscErrorCode PetscSpaceGetDegree(PetscSpace sp, PeOp PetscInt *minDegree, PeOp PetscInt *maxDegree)
    344: {
    345:   PetscFunctionBegin;
    347:   if (minDegree) PetscAssertPointer(minDegree, 2);
    348:   if (maxDegree) PetscAssertPointer(maxDegree, 3);
    349:   if (minDegree) *minDegree = sp->degree;
    350:   if (maxDegree) *maxDegree = sp->maxDegree;
    351:   PetscFunctionReturn(PETSC_SUCCESS);
    352: }

    354: /*@
    355:   PetscSpaceSetDegree - Set the degree of approximation for this space.

    357:   Input Parameters:
    358: + sp        - The `PetscSpace`
    359: . degree    - The degree of the largest polynomial space contained in the space
    360: - maxDegree - The degree of the largest polynomial space containing the space.  One of degree and maxDegree can be `PETSC_DETERMINE`.

    362:   Level: intermediate

    364: .seealso: `PetscSpace`, `PetscSpaceGetDegree()`, `PetscSpaceCreate()`
    365: @*/
    366: PetscErrorCode PetscSpaceSetDegree(PetscSpace sp, PetscInt degree, PetscInt maxDegree)
    367: {
    368:   PetscFunctionBegin;
    370:   sp->degree    = degree;
    371:   sp->maxDegree = maxDegree;
    372:   PetscFunctionReturn(PETSC_SUCCESS);
    373: }

    375: /*@
    376:   PetscSpaceGetNumComponents - Return the number of components for this space

    378:   Input Parameter:
    379: . sp - The `PetscSpace`

    381:   Output Parameter:
    382: . Nc - The number of components

    384:   Level: intermediate

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

    389: .seealso: `PetscSpace`, `PetscSpaceSetNumComponents()`, `PetscSpaceGetNumVariables()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
    390: @*/
    391: PetscErrorCode PetscSpaceGetNumComponents(PetscSpace sp, PetscInt *Nc)
    392: {
    393:   PetscFunctionBegin;
    395:   PetscAssertPointer(Nc, 2);
    396:   *Nc = sp->Nc;
    397:   PetscFunctionReturn(PETSC_SUCCESS);
    398: }

    400: /*@
    401:   PetscSpaceSetNumComponents - Set the number of components for this space

    403:   Input Parameters:
    404: + sp - The `PetscSpace`
    405: - Nc - The number of components

    407:   Level: intermediate

    409: .seealso: `PetscSpace`, `PetscSpaceGetNumComponents()`, `PetscSpaceSetNumVariables()`, `PetscSpaceCreate()`
    410: @*/
    411: PetscErrorCode PetscSpaceSetNumComponents(PetscSpace sp, PetscInt Nc)
    412: {
    413:   PetscFunctionBegin;
    415:   sp->Nc = Nc;
    416:   PetscFunctionReturn(PETSC_SUCCESS);
    417: }

    419: /*@
    420:   PetscSpaceSetNumVariables - Set the number of variables for this space

    422:   Input Parameters:
    423: + sp - The `PetscSpace`
    424: - n  - The number of variables, e.g. x, y, z...

    426:   Level: intermediate

    428: .seealso: `PetscSpace`, `PetscSpaceGetNumVariables()`, `PetscSpaceSetNumComponents()`, `PetscSpaceCreate()`
    429: @*/
    430: PetscErrorCode PetscSpaceSetNumVariables(PetscSpace sp, PetscInt n)
    431: {
    432:   PetscFunctionBegin;
    434:   sp->Nv = n;
    435:   PetscFunctionReturn(PETSC_SUCCESS);
    436: }

    438: /*@
    439:   PetscSpaceGetNumVariables - Return the number of variables for this space

    441:   Input Parameter:
    442: . sp - The `PetscSpace`

    444:   Output Parameter:
    445: . n - The number of variables, e.g. x, y, z...

    447:   Level: intermediate

    449: .seealso: `PetscSpace`, `PetscSpaceSetNumVariables()`, `PetscSpaceGetNumComponents()`, `PetscSpaceGetDimension()`, `PetscSpaceCreate()`
    450: @*/
    451: PetscErrorCode PetscSpaceGetNumVariables(PetscSpace sp, PetscInt *n)
    452: {
    453:   PetscFunctionBegin;
    455:   PetscAssertPointer(n, 2);
    456:   *n = sp->Nv;
    457:   PetscFunctionReturn(PETSC_SUCCESS);
    458: }

    460: /*@
    461:   PetscSpaceEvaluate - Evaluate the basis functions and their derivatives (jet) at each point

    463:   Input Parameters:
    464: + sp      - The `PetscSpace`
    465: . npoints - The number of evaluation points, in reference coordinates
    466: - points  - The point coordinates

    468:   Output Parameters:
    469: + B - The function evaluations in a `npoints` x `nfuncs` array
    470: . D - The derivative evaluations in a `npoints` x `nfuncs` x `dim` array
    471: - H - The second derivative evaluations in a `npoints` x `nfuncs` x `dim` x `dim` array

    473:   Level: beginner

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

    479: .seealso: `PetscSpace`, `PetscFECreateTabulation()`, `PetscFEGetCellTabulation()`, `PetscSpaceCreate()`
    480: @*/
    481: PetscErrorCode PetscSpaceEvaluate(PetscSpace sp, PetscInt npoints, const PetscReal points[], PeOp PetscReal B[], PeOp PetscReal D[], PeOp PetscReal H[])
    482: {
    483:   PetscFunctionBegin;
    484:   if (!npoints) PetscFunctionReturn(PETSC_SUCCESS);
    486:   if (sp->Nv) PetscAssertPointer(points, 3);
    487:   if (B) PetscAssertPointer(B, 4);
    488:   if (D) PetscAssertPointer(D, 5);
    489:   if (H) PetscAssertPointer(H, 6);
    490:   PetscTryTypeMethod(sp, evaluate, npoints, points, B, D, H);
    491:   PetscFunctionReturn(PETSC_SUCCESS);
    492: }

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

    497:   Not Collective

    499:   Input Parameters:
    500: + sp     - the `PetscSpace` object
    501: - height - the height of the mesh point for which the subspace is desired

    503:   Output Parameter:
    504: . subsp - the subspace

    506:   Level: advanced

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

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

    515: .seealso: `PetscDualSpaceGetHeightSubspace()`, `PetscSpace`
    516: @*/
    517: PetscErrorCode PetscSpaceGetHeightSubspace(PetscSpace sp, PetscInt height, PetscSpace *subsp)
    518: {
    519:   PetscFunctionBegin;
    521:   PetscAssertPointer(subsp, 3);
    522:   *subsp = NULL;
    523:   PetscTryTypeMethod(sp, getheightsubspace, height, subsp);
    524:   PetscFunctionReturn(PETSC_SUCCESS);
    525: }