1 /* 2 Provides utility routines for manulating any type of PETSc object. 3 */ 4 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/ 5 6 /*@ 7 PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()` 8 9 Collective 10 11 Input Parameter: 12 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 13 14 Output Parameter: 15 . options - the options database 16 17 Level: advanced 18 19 Note: 20 If this is not called the object will use the default options database 21 22 Developer Notes: 23 This functionality is not used in PETSc and should, perhaps, be removed 24 25 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 26 `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()` 27 @*/ 28 PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options) 29 { 30 PetscFunctionBegin; 31 PetscValidHeader(obj, 1); 32 *options = obj->options; 33 PetscFunctionReturn(PETSC_SUCCESS); 34 } 35 36 /*@ 37 PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object. 38 39 Collective 40 41 Input Parameters: 42 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 43 - options - the options database, use NULL for default 44 45 Level: advanced 46 47 Note: 48 If this is not called the object will use the default options database 49 50 Developer Notes: 51 This functionality is not used in PETSc and should, perhaps, be removed 52 53 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 54 `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()` 55 @*/ 56 PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options) 57 { 58 PetscFunctionBegin; 59 PetscValidHeader(obj, 1); 60 obj->options = options; 61 PetscFunctionReturn(PETSC_SUCCESS); 62 } 63 64 /*@ 65 PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all 66 options for the given object in the database. 67 68 Collective 69 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. 73 74 Level: advanced 75 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. 80 81 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 82 `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()` 83 @*/ 84 PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[]) 85 { 86 PetscFunctionBegin; 87 PetscValidHeader(obj, 1); 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 size_t len; 93 94 PetscCall(PetscFree(obj->prefix)); 95 PetscCall(PetscStrlen(prefix, &len)); 96 if (len) PetscCall(PetscStrallocpy(prefix, &obj->prefix)); 97 } 98 } else PetscCall(PetscFree(obj->prefix)); 99 PetscFunctionReturn(PETSC_SUCCESS); 100 } 101 102 /*@ 103 PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database. 104 105 Input Parameters: 106 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 107 - prefix - the prefix string to prepend to option requests of the object. 108 109 Level: advanced 110 111 Note: 112 A hyphen (-) must NOT be given at the beginning of the prefix name. 113 The first character of all runtime options is AUTOMATICALLY the 114 hyphen. 115 116 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 117 `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()` 118 @*/ 119 PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[]) 120 { 121 size_t len1, len2, new_len; 122 123 PetscFunctionBegin; 124 PetscValidHeader(obj, 1); 125 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 126 if (!obj->prefix) { 127 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 128 PetscFunctionReturn(PETSC_SUCCESS); 129 } 130 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 131 132 PetscCall(PetscStrlen(obj->prefix, &len1)); 133 PetscCall(PetscStrlen(prefix, &len2)); 134 new_len = len1 + len2 + 1; 135 PetscCall(PetscRealloc(new_len * sizeof(*obj->prefix), &obj->prefix)); 136 PetscCall(PetscStrncpy(obj->prefix + len1, prefix, len2 + 1)); 137 PetscFunctionReturn(PETSC_SUCCESS); 138 } 139 140 /*@ 141 PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database 142 143 Input Parameter: 144 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 145 146 Output Parameter: 147 . prefix - pointer to the prefix string used is returned 148 149 Level: advanced 150 151 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 152 `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()` 153 @*/ 154 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[]) 155 { 156 PetscFunctionBegin; 157 PetscValidHeader(obj, 1); 158 PetscAssertPointer(prefix, 2); 159 *prefix = obj->prefix; 160 PetscFunctionReturn(PETSC_SUCCESS); 161 } 162 163 /*@ 164 PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database. 165 166 Input Parameters: 167 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 168 - prefix - the prefix string to prepend to option requests of the object. 169 170 Level: advanced 171 172 Note: 173 A hyphen (-) must NOT be given at the beginning of the prefix name. 174 The first character of all runtime options is AUTOMATICALLY the 175 hyphen. 176 177 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, 178 `PetscObjectGetOptionsPrefix()` 179 @*/ 180 PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[]) 181 { 182 char *buf; 183 size_t len1, len2, new_len; 184 185 PetscFunctionBegin; 186 PetscValidHeader(obj, 1); 187 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 188 if (!obj->prefix) { 189 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 190 PetscFunctionReturn(PETSC_SUCCESS); 191 } 192 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 193 194 PetscCall(PetscStrlen(prefix, &len1)); 195 PetscCall(PetscStrlen(obj->prefix, &len2)); 196 buf = obj->prefix; 197 new_len = len1 + len2 + 1; 198 PetscCall(PetscMalloc1(new_len, &obj->prefix)); 199 PetscCall(PetscStrncpy(obj->prefix, prefix, len1 + 1)); 200 PetscCall(PetscStrncpy(obj->prefix + len1, buf, len2 + 1)); 201 PetscCall(PetscFree(buf)); 202 PetscFunctionReturn(PETSC_SUCCESS); 203 } 204