Date: 2025-03-28T21:11:12+00:00

Actual source code: prefix.c

      1: /*
      2:      Provides utility routines for manulating any type of PETSc object.
      3: */
      4: #include <petsc/private/petscimpl.h>

      6: /*@
      7:   PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()`

      9:   Collective

     11:   Input Parameter:
     12: . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

     14:   Output Parameter:
     15: . options - the options database

     17:   Level: advanced

     19:   Note:
     20:   If this is not called the object will use the default options database

     22:   Developer Notes:
     23:   This functionality is not used in PETSc and should, perhaps, be removed

     25: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     26:           `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()`
     27: @*/
     28: PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options)
     29: {
     30:   PetscFunctionBegin;
     32:   *options = obj->options;
     33:   PetscFunctionReturn(PETSC_SUCCESS);
     34: }

     36: /*@
     37:   PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.

     39:   Collective

     41:   Input Parameters:
     42: + obj     - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
     43: - options - the options database, use NULL for default

     45:   Level: advanced

     47:   Note:
     48:   If this is not called the object will use the default options database

     50:   Developer Notes:
     51:   This functionality is not used in PETSc and should, perhaps, be removed

     53: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     54:           `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()`
     55: @*/
     56: PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options)
     57: {
     58:   PetscFunctionBegin;
     60:   obj->options = options;
     61:   PetscFunctionReturn(PETSC_SUCCESS);
     62: }

     64: /*@
     65:   PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
     66:   options for the given object in the database.

     68:   Collective

     70:   Input Parameters:
     71: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
     72: - prefix - the prefix string to prepend to option requests of the object.

     74:   Level: advanced

     76:   Note:
     77:   A hyphen (-) must NOT be given at the beginning of the prefix name.
     78:   The first character of all runtime options is AUTOMATICALLY the
     79:   hyphen.

     81: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     82:           `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()`
     83: @*/
     84: PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[])
     85: {
     86:   PetscFunctionBegin;
     88:   if (prefix) {
     89:     PetscAssertPointer(prefix, 2);
     90:     PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");
     91:     if (prefix != obj->prefix) {
     92:       PetscCall(PetscFree(obj->prefix));
     93:       PetscCall(PetscStrallocpy(prefix, &obj->prefix));
     94:     }
     95:   } else PetscCall(PetscFree(obj->prefix));
     96:   PetscFunctionReturn(PETSC_SUCCESS);
     97: }

     99: /*@
    100:   PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database.

    102:   Input Parameters:
    103: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
    104: - prefix - the prefix string to prepend to option requests of the object.

    106:   Level: advanced

    108:   Note:
    109:   A hyphen (-) must NOT be given at the beginning of the prefix name.
    110:   The first character of all runtime options is AUTOMATICALLY the
    111:   hyphen.

    113: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
    114:           `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
    115: @*/
    116: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
    117: {
    118:   size_t len1, len2, new_len;

    120:   PetscFunctionBegin;
    122:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
    123:   if (!obj->prefix) {
    124:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
    125:     PetscFunctionReturn(PETSC_SUCCESS);
    126:   }
    127:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

    129:   PetscCall(PetscStrlen(obj->prefix, &len1));
    130:   PetscCall(PetscStrlen(prefix, &len2));
    131:   new_len = len1 + len2 + 1;
    132:   PetscCall(PetscRealloc(new_len * sizeof(*obj->prefix), &obj->prefix));
    133:   PetscCall(PetscStrncpy(obj->prefix + len1, prefix, len2 + 1));
    134:   PetscFunctionReturn(PETSC_SUCCESS);
    135: }

    137: /*@
    138:   PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database

    140:   Input Parameter:
    141: . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

    143:   Output Parameter:
    144: . prefix - pointer to the prefix string used is returned

    146:   Level: advanced

    148: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
    149:           `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()`
    150: @*/
    151: PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[])
    152: {
    153:   PetscFunctionBegin;
    155:   PetscAssertPointer(prefix, 2);
    156:   *prefix = obj->prefix;
    157:   PetscFunctionReturn(PETSC_SUCCESS);
    158: }

    160: /*@
    161:   PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database.

    163:   Input Parameters:
    164: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
    165: - prefix - the prefix string to prepend to option requests of the object.

    167:   Level: advanced

    169:   Note:
    170:   A hyphen (-) must NOT be given at the beginning of the prefix name.
    171:   The first character of all runtime options is AUTOMATICALLY the
    172:   hyphen.

    174: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`,
    175:           `PetscObjectGetOptionsPrefix()`
    176: @*/
    177: PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[])
    178: {
    179:   char  *buf;
    180:   size_t len1, len2, new_len;

    182:   PetscFunctionBegin;
    184:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
    185:   if (!obj->prefix) {
    186:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
    187:     PetscFunctionReturn(PETSC_SUCCESS);
    188:   }
    189:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

    191:   PetscCall(PetscStrlen(prefix, &len1));
    192:   PetscCall(PetscStrlen(obj->prefix, &len2));
    193:   buf     = obj->prefix;
    194:   new_len = len1 + len2 + 1;
    195:   PetscCall(PetscMalloc1(new_len, &obj->prefix));
    196:   PetscCall(PetscStrncpy(obj->prefix, prefix, len1 + 1));
    197:   PetscCall(PetscStrncpy(obj->prefix + len1, buf, len2 + 1));
    198:   PetscCall(PetscFree(buf));
    199:   PetscFunctionReturn(PETSC_SUCCESS);
    200: }