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 /*@C 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 /*@C 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 /*@C 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 PetscCall(PetscFree(obj->prefix)); 93 PetscCall(PetscStrallocpy(prefix, &obj->prefix)); 94 } 95 } else PetscCall(PetscFree(obj->prefix)); 96 PetscFunctionReturn(PETSC_SUCCESS); 97 } 98 99 /*@C 100 PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database. 101 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. 105 106 Level: advanced 107 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. 112 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; 119 120 PetscFunctionBegin; 121 PetscValidHeader(obj, 1); 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"); 128 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 } 136 137 /*@C 138 PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database 139 140 Input Parameter: 141 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 142 143 Output Parameter: 144 . prefix - pointer to the prefix string used is returned 145 146 Level: advanced 147 148 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 149 `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()` 150 @*/ 151 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[]) 152 { 153 PetscFunctionBegin; 154 PetscValidHeader(obj, 1); 155 PetscAssertPointer(prefix, 2); 156 *prefix = obj->prefix; 157 PetscFunctionReturn(PETSC_SUCCESS); 158 } 159 160 /*@C 161 PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database. 162 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. 166 167 Level: advanced 168 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. 173 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; 181 182 PetscFunctionBegin; 183 PetscValidHeader(obj, 1); 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"); 190 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 } 201